Under construction

Setting up your computer to run Bwb

Overview: Running Bwb

1. Install Docker.

2. Start the container with Bwb by executing the following Docker command by typing into a window (Linux) or on the Docker command line (Windows/MacOS). For Windows, it may be necessary to run the Docker application as an Administrator.

Linux/Mac

sudo docker run --rm   -p 6080:6080 \
    -v  ${PWD}/:/data  \
    -v  /var/run/docker.sock:/var/run/docker.sock \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    --privileged --group-add root \
    biodepot/bwb

Windows

docker run --rm   -p 6080:6080 \
    -v  /c/users:/data  \
    -v  /var/run/docker.sock:/var/run/docker.sock \
    -v /tmp/.X11-unix:/tmp/.X11-unix \
    --privileged --group-add root \
    biodepot/bwb

3. Open a browser and connect to the Bwb container by typing the following url in the address bar of your browser:

http://localhost:6080

NOTE: the vnc password is set to bwb

For cloud instances and remote servers use the IP of the instance or remote server instead of localhost.

For Windows and Macs the IP may vary depending on your setup.

Windows 10 Pro and newer Macs running native Docker will use the same localhost setup. Windows 7, 8 and 10 Home edition, and older Macs that use a Virtual machine (VM) will need to use the IP of the virtual machine instead of localhost - usually 192.168.99.100. In addition, for these VM setups, the available RAM of the VM limits the RAM that can be used (usually 1 or 2 GB only). The VM settings must be adjusted to increase the available memory for applications such as Kallisto (roughly 8 GB and STAR (roughly 32 GB for human datasets).

4. To quit the container, right click inside the browser and choose the QUIT container option. Alternatively, you can also stop it by finding the container id and stopping the container. Quitting the browser just closes the viewport to the container - it does not stop the container.

Using a VNC client

In addition to being able to connect with a browser it is also possible to use a dedicated VNC client. Real VNC Free version is one that we use. Using a VNC client makes all the control key combinations available and cut-and-paste from outside Bwb into Bwb available without using the side menu as in the browser connection.

For a VNC connection you must add the flag

-p 5900:5900

to the Docker command to expose the port to communicate with the VNC client. Then connect your client to localhost:5900 if you are running Bwb locally or :5900 if you are running on the cloud. You will need to open the port if running on the cloud - follow the instructions here but substituting 5900 for 6080.

Installing and starting Docker

Linux

1. Update your package manager index.

On Debian based distros such as Ubuntu the package manager is apt-get

sudo apt-get -y update

On Redhat based distros such as Fedora/Centos the package manager is dnf or yum on older systems

sudo dnf -y update

2. Install Docker.

Ubuntu:

sudo apt-get -y install docker-engine

Fedora/Centos:

sudo dnf -y install docker

3. Start the Docker daemon.

sudo service docker start

4. Verify docker is installed correctly.

sudo docker run hello-world

The last command downloads a test image and runs it in a container. When the container runs, it prints an informational message and then exits.

For more information please refer to:

https://docs.docker.com/engine/installation/

Windows or MacOS

Method 1 Install Linux VM

There are two viable routes for installing Docker on non-Linux platforms. The preferred method is to install a Linux (Ubuntu) virtual machine (VM) and follow the instructions for installing Docker on Linux. This is currently tghe most reliable option.

On Windows 10/11, WSL2 provides an Ubuntu VM out of the box https://www.redswitches.com/blog/use-wsl2-to-install-ubuntu-on-windows/. VirtualBox also works well https://automaticaddison.com/how-to-install-ubuntu-and-virtualbox-on-a-windows-pc/.

For Macs, Multipass is a recommended. It is fast, runs natively on Mac M1/M2 and comes with a pre-build Docker/Ubuntu VM https://ubuntu.com/blog/docker-on-mac-a-lightweight-option-with-multipass

Method 2 Install Docker Desktop

The second option, is to use the Docker for Windows/Mac Docker for Desktop installers. This is free for most users but we find that the process has become complicated especially with managing file permissions. https://www.docker.com/products/docker-desktop/

Starting Bwb

After you have installed Docker on your machine, you are now ready to start your Bwb session to create and execute Docker container workflows. Bwb comes inside its own Docker container so it is first necessary to launch Docker as shown in the previous sections depending on which platform is being used.

Then run the following commands on the command prompt / terminal.

1. Download the docker image containing Bwb.

docker pull biodepot/bwb:latest

Alternatively, you can build the image from the GitHub repo:

On Linux and Macs

git clone https://github.com/BioDepot/BioDepot-workflow-builder.git
cd BioDepot-workflow-builder
sudo docker build -t biodepot/bwb:latest .

On Windows (using Git for Windows)

Right-click on the git bash icon and choose to run as an administrator:

git config --system core.longpaths true
git clone https://github.com/BioDepot/BioDepot-workflow-builder.git
cd BioDepot-workflow-builder
docker build -t biodepot/bwb:latest .

2. Start the Bwb container.

For Linux/MacOS

sudo docker run --rm -p 6080:6080 -v ${PWD}:/data -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/.X11-unix:/tmp/.X11-unix  --privileged --group-add root biodepot/bwb

For Windows

docker run --rm -p 6080:6080 -v /c/users:/data -v /var/run/docker.sock:/var/run/docker.sock -v /tmp/.X11-unix:/tmp/.X11-unix  --privileged --group-add root biodepot/bwb

This command will launch a mini-webserver and start a windowing environment inside the container. The Bwb application is automatically launched upon running the container and appears as a maximized window on the Desktop inside the container. In the above command we have set the port to be 6080. For Linux/MacOS the current directory is mapped to the /data directory inside the container. For Windows, by default the C://Users directory is made available for Docker and we map this to the /data directory in side the container. Other mappings are possible However, all this is hidden from view until the user connects to the container using a browser.

To access the container open up a browser window and type in the IP of the container, and port that it is listening to, into the address bar. For a local installation using Linux, the IP of the container is localhost or 127.0.0.1 so the user would type localhost:6080 into the address bar of the browser. For a remote installation, the IP is the IP of the server.

For Macs and Windows machines using VirtualBox, the local IP is usually 192:168:99:100. If that does not work, you can find the IP with the following command in a terminal if using Linux/MacOS, or in the Docker window if using Windows.

docker ps

Alternatively, you can run a simple docker command:

docker run --rm --net host alpine ip address

More information about finding Docker IP is available here: https://docs.docker.com/machine/reference/ip