How to run TBAS with Docker

Install Docker

Install Docker CE (Stable) on your computer using instructions at Docker.com

Run all docker commands as superuser or administrator, except when using Docker Toolbox.

For Windows try running all commands in Windows Powershell (instead of the Docker quickstart).

In Linux this means running as root or prepending all commands with sudo. When running commands with sudo try not to confuse the sudo password with the docker repository password when running that command.

When Docker is installed and working correctly you should be able to run the Docker hello world image by typing in your terminal

sudo docker run hello-world

Installation on legacy Windows and Mac

Applies to all Windows versions except Windows 10 Professional or Enterprise 64-bit
Applies to all Mac versions prior to OSX Yosemite 10.10.3

Install the Docker Desktop for Windows or Mac

Double-click Docker Quickstart terminal to launch, and it should open a DOS window. It will take a minute or two to "boot." When it finishes you will just see a command line.

From here you should be able to enter the commands.

To go to the web site instead of going to localhost use the IP given at the top of the DOS window. It should give the IP in a line like 'docker is configured to use the default machine with IP 192.168.99.100'.

Get TBAS2 Docker container

The TBAS Docker registry is hosted at docker hub.

First register at docker hub at https://hub.docker.com/signup

Then email us your user id and we will add you as collaborator.

Next login with your username. The example below is the ncsudecifr login.

sudo docker login
Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
Username: ncsudecifr
Password:
WARNING! Your password will be stored unencrypted in /home/jim/.docker/config.json.
Configure a credential helper to remove this warning. See
https://docs.docker.com/engine/reference/commandline/login/#credentials-store

Login Succeeded

Next pull the image from the repository. This is a large file so might not want to try on a connection without bandwidth.

sudo docker pull icarbone/tbas2:v2.2

Run TBAS2 Docker container

sudo docker run -p 8888:80 -d  --rm icarbone/tbas2:v2.2

This is an example that starts the TBAS container which can now be accessed on port 8888 at localhost

Running in this mode log files and temporary files are written inside the docker container. This may be easier to start for first time users or if just one run is needed. However, for data and logfiles to persist after a container is stopped, for example by turning off the computer, it is better to use the command that saves logs and data to the local computer.

sudo docker run -p 8888:80 -d \
-v /var/www/html/tbas2_1/tmp:/var/www/html/tbas2_1/tmp \
-v /var/www/html/tbas2_1/logs:/var/www/html/tbas2_1/logs \
--rm icarbone/tbas2:v2.2

There are three things to note about the above command.

First, is the port where TBAS is accessable is set with the -p option, in this case port 8888.

Most importantly are the 2 lines with -v which tell where on you local computer to put the tmp files and log files. Edit ONLY the part of these 2 lines before the : to a directory on your computer.

If TBAS fails to run correctly one possible problem is the permissions on the tmp and logs directories. Use the chmod command to fix it.

jim@jim-OptiPlex-7040 ~/Downloads/tbas1docker $ ls -l
total 8
drwxr-xr-x 2 root root 4096 Jun  7 14:23 logs
drwxr-xr-x 2 root root 4096 Jun  7 14:23 tmp
jim@jim-OptiPlex-7040 ~/Downloads/tbas1docker $ sudo chmod 777 tmp
jim@jim-OptiPlex-7040 ~/Downloads/tbas1docker $ sudo chmod 777 logs
jim@jim-OptiPlex-7040 ~/Downloads/tbas1docker $ ls -l
total 8
drwxrwxrwx 2 root root 4096 Jun  7 14:25 logs
drwxrwxrwx 3 root root 4096 Jun  7 14:25 tmp``

Here is an example of how to start the container on Windows and mount external volumes.

C:\Users\Ignazio Carbone>cd Desktop
C:\Users\Ignazio Carbone\Desktop>mkdir tbas
C:\Users\Ignazio Carbone\Desktop>cd tbas
C:\Users\Ignazio Carbone\Desktop\tbas>mkdir logs
C:\Users\Ignazio Carbone\Desktop\tbas>mkdir tmp

C:\Users\Ignazio Carbone\Desktop\tbas\logs>docker ps
CONTAINER ID   IMAGE                 COMMAND                  CREATED         STATUS         PORTS                  NAMES
ab18a0c8de47   icarbone/tbas2:v2.2   "/usr/sbin/apache2ct…"   7 minutes ago   Up 6 minutes   0.0.0.0:8888->80/tcp   practical_boyd

C:\Users\Ignazio Carbone\Desktop\tbas\logs>docker stop ab18a0c8de47
ab18a0c8de47

C:\Users\Ignazio Carbone\Desktop\tbas\logs>docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

C:\Users\Ignazio Carbone\Desktop\tbas\logs>docker run -p 8888:80 -d -v C:/Users/"Ignazio Carbone"/Desktop/tbas/tmp:/var/www/html/tbas2_1/tmp -v C:/Users/"Ignazio Carbone"/Desktop/tbas/logs:/var/www/html/tbas2_1/logs --rm icarbone/tbas2:v2.2
e73c6cb59f42eada7fa809e810ff695c50d2371ccc7189f85aa5198ceeb5249b

How to test connection to TBAS user database

If you get a failed to connect to database error, then you will need to be sure your firewall is open to host db-postgresql-nyc3-83355-do-user-8906009-0.b.db.ondigitalocean.com on port 25060 and also that the Digital Ocean server is accepting connections from your IP. You will need to have us open the Digital Ocean firewall to your IP which you can find several ways. One way is with https://ipecho.net/.

You can test the connection from your docker container:

$ sudo docker ps
[sudo] password for jim:
CONTAINER ID   IMAGE     COMMAND                  CREATED          STATUS          PORTS                                   NAMES
40743e8a2ebf   tbas2     "/usr/sbin/apache2ct…"   26 minutes ago   Up 26 minutes   0.0.0.0:8888->80/tcp, :::8888->80/tcp   trusting_lehmann
jim@intrex-intel:/var/www/docker/tbas2$ sudo docker exec -it 40743e8a2ebf bash
root@40743e8a2ebf:/var/www/html/tbas2_1# telnet db-postgresql-nyc3-83355-do-user-8906009-0.b.db.ondigitalocean.com 25060
Trying 209.97.145.49...
Connected to db-postgresql-nyc3-83355-do-user-8906009-0.b.db.ondigitalocean.com.
Escape character is '^]'.

If you get something like this then a firewall is blocking.

root@40743e8a2ebf:/var/www/html/tbas2_1# telnet db-postgresql-nyc3-83355-do-user-8906009-0.b.db.ondigitalocean.com 25060
Trying 209.97.145.49...

T-BAS documentation

Documentation and tutorials for T-BAS are available in the docker container under the Utilities menu or the public T-BAS pages.

Memory error on virtual machine

When installing on a non-linux computer the virtual machine to run the container may need to adjust the available memory or some programs may fail, esp. MAFFT. See example for installation on a Mac adjusting 2GB to 8GB.

Run multiple containers

It is possible to run multiple containers instead of stopping and starting a new container.

Start a container on another port, eg 8889:

sudo docker run -p 8889:80 -d \
-v /var/www/html/tbas2_1/tmp:/var/www/html/tbas2_1/tmp \
-v /var/www/html/tbas2_1/logs:/var/www/html/tbas2_1/logs \
--rm icarbone/tbas2:v2.2

The assignments report has a link column to show placement on the tree. It is set by default to http://localhost:8888. To change it you need to access the container with the exec command (see below). Edit the /var/www/html/tbas2_/pages/tbas.ini file as shown in this screenshot ini file and set the hostname.

Notes

The login on the TBAS start page is the same as the username and pin for TBAS hosted at NCSU. This page connects to the AWS database server to verify that the user has registered as a TBAS user.

The programs BLAST, MAFFT, and RAxML are not run on CIPRES with parallel CPUs so run times for placement will be different. Some will be faster because there is no waiting in a queue to run but some will take longer due to running on one CPU instead of multiple CPUs.

More Docker commands

Docker images use disk space. These commands can reclaim disk space.

The second command will remove unused images and also any images that are not associated with a running container, i.e. you may need to download new images from docker hub.

sudo docker system prune -a
sudo docker system prune -a --volumes
This command shows the image and id of container you are running.
docker ps

Example:

sudo docker ps
CONTAINER ID   IMAGE                 COMMAND                  CREATED          STATUS          PORTS                  NAMES
76a5efed6c92   icarbone/tbas2:v2.2   "/usr/local/bin/supe…"   27 seconds ago   Up 26 seconds   0.0.0.0:8888->80/tcp   suspicious_noether
This command will stop the running container.
sudo docker stop <container-id>

Example:

sudo docker stop 76a5efed6c92
76a5efed6c92
This command will allow you access to the container if you want to see what's inside.
sudo docker exec -it <container-id> bash

Example:

This example shows how to look in the container and inspect the shell scripts that run the program commands. These scripts could be edited here to run with different options and executables.

sudo docker exec -it 4e535cc784ff bash
root@4e535cc784ff:/var/www/html/tbas1_0# cd scripts
root@4e535cc784ff:/var/www/html/tbas1_0/scripts# ls
blast_parser.pl  run_mafft.sh  run_raxml.sh  run_silva_blast.sh  run_similarity.sh  run_unite_blast.sh
root@4e535cc784ff:/var/www/html/tbas1_0/scripts# cat run_mafft.sh
#!/bin/bash

runnum="$1"
cd /var/www/html/tbas1_0/tmp
mkdir "mafft_results_tmp${runnum}"
mkdir "mafft_results${runnum}"

cd "mafft_results_tmp${runnum}"
cp "../${runnum}.fas" input.fasta
cp "../add_alignment${runnum}.fascln" existing_alignment.fasta

mafft --inputorder --ep 0.0 --auto --anysymbol --adjustdirection --add input.fasta --reorder existing_alignment.fasta > output.mafft 2> STDERR

cd "../mafft_results${runnum}"
echo "Options +Indexes" > .htaccess
cp "../mafft_results_tmp${runnum}/output.mafft" input.fasta

mafft  --inputorder --maxiterate 0 --retree 2 --anysymbol input.fasta > output.mafft 2> STDERR