Biodepot Launcher

The Biodepot Launcher is a web application that facilitates the installation, management and execution of bioinformatics workflows in the Bwb. This web application provides an interactive and easy-to-use interface to deploy containerized analytical workflows to process biomedical data. It is written in React and Javascript and tested using Firefox and Google Chrome browsers across multiple operating systems. After Docker is installed, it is very simple to run this web application. The Launcher can run on the following operating systems: Ubuntu, Windows 10/11 WSL2 Ubuntu, and macOS (M-Series mac).

Installation:

To run Biodepot Launcher, one must first download the most current version of the binaries from GitHub. Unzip the Launcher archive from this LINK and all the contents into a folder. Inside the unzipped folder, there will be binaries following a naming convention that ends with the OS and architecture of your CPU. The first asterisk will be either "linux", or "mac", which is representative of the operating system that is running on your machine. The second asterisk indicates the architecture of your CPU. Once the binary is unzipped, and selected, the binary can be run with a simple double-click. In addition to the launcher binary, there are additional dependencies to launch any workflow.

Note

For macOS: When opening the binary for the first time, there will be a security prompt. While the prompt is showing, navigate to the Security and Privacy menu in the System Settings and click the "Open Anyway" button for the application. This allows the binary to be opened.

Biodepot Launcher has multiple dependencies for launching Bwb workflows, both locally and on AWS. These dependencies are Docker, AWS CLI, and Docker Machine. Docker is the only required dependency and the user will not be able to use the application if Docker is not installed. Optional dependencies are AWS CLI and Docker Machine. If launching on AWS is necessary, then AWS CLI will need to be installed. Additionally, for simplicity, Docker Machine can be installed to keep track of and remove running EC2 instances. Scripts to install Docker Machine have been included in the binaries.zip file to simplify the installation of Docker Machine.

The Docker Machine scripts included with the binaries.zip file installs the most recent version of Docker Machine. The Mac and Ubuntu versions can be run from the command line. The Mac version uses brew to install Docker Machine, while the Ubuntu version installs Docker Machine to a folder within the home directory. Take note that the Ubuntu version requires that the user restart their machine for Docker Machine to be accessible from anywhere on the command line. For Windows WSL2, the Ubuntu version should be used. Please follow the directions on GitHub if further clarification is needed

Navigating the Launcher:

<

When starting Biodepot Launcher, users see a sidebar with a black background and a large portion of the window with a white background, this larger portion can be referred to as the main pane. The sidebar lists the “Workflow repository” button, a “Reload” button, the “Installed Workflows” buttons, the “Bwb Docs” button, and the "GitPod Docs" button. Figure 2 shows a screenshot of the interface when Biodepot Launcher starts.

A reload button is included to refresh the interface incase locally installed workflows get out of sync with the Launcher. The Launcher is not meant to be left open while the user is making changes to workflows as Biodepot Launcher cannot detect these changes without a reload.

The “Workflow repository” button, when clicked, will show the workflows available for download. This button is automatically selected when starting the Launcher. The workflows in the main pane are listed by type. The types are DNA, RNA, general, serverless, and nanopore. To download workflows from these additional types, click on the type button in the main pane. For each workflow, its name is listed and the option to install the workflow by clicking on the “Install Now” button. Clicking the “Install Now” button will activate a download of the workflow to the computer that you launched the Launcher from. When the workflow finishes downloading, the text in the button will change to “Installed” and the once yellow dot in the button will change to green.

Note

When downloading/updating/rebasing a workflow, there will be a spinner displayed on the screen. When this spinner is displayed, allow the operation to finish before clicking on anything else in the launcher.

When installed workflows need to be used, the “Installed Workflows” buttons can be selected. First, select the type of workflow from the list of “Installed Workflows” buttons. Once a type is selected, the button will have a purple background, and you will see your previously downloaded workflows in the main pane labeled “Installed”.

For each installed workflow, there are actions that can be taken. First, the workflow name will be listed with an associated colored dot as an indicator. The colored dot is green if the locally installed workflow is current with the one on GitHub. If the local workflow and the workflow on GitHub are not the same, the indicator dot will turn yellow and the text of the button next to it will be “Update Available”.

Selecting the “Update Available” button will start a process that will update the local workflow to the more current one on GitHub. Selecting the “Rebase” icon, which is a circular arrow, will roll back all changes made to the workflow since the last install/update. In both cases, all changes made by the user will be lost and there will be a prompt indicating this before the user makes a final decision.

In addition, there will be two icons present for each workflow listed. The first icon will be a book indicating if associated documentation is present for the workflow on GitHub. Clicking this documentation icon will open the documentation in a new browser window. If the documentation is not available on GitHub, the documentation icon will be grayed out.

The second of the two icons (a small computer) present for each workflow is the launcher options icon. Selecting this icon will bring up several launch options for Bwb. The options present are to launch in the “Browser”, on "GitPod, and on “AWS”. Selecting the "Browser" button will open Bwb in a new browser window.

The "GitPod" launch option does not require any additional dependencies besides Biodepot Launcher to be installed. Selecting "GitPod" will launch the workflow in the cloud. Instructions for how to use GitPod can be found by scrolling-down the sidebar and selecting the "GitPod Docs" button, or clicking on this LINK. To launch a workflow on AWS, you will need AWS CLI installed, along with Docker Machine. Selecting the "AWS" button will bring the user to an additional pop-up that allows selection of a "Region" and the "Instance Type". The user can choose to select from the drop-down menus, or enter the values manually.

Note

Launching on AWS currently requires that the user use the us-east-2 (Ohio) region.