10. Troubleshooting Containers

Docker

Container Testing

Say we run into an issue running a specific container (e.g. IQTREE) on our file system. We might want to do some local troubleshooting to identify what's going wrong. Let's start by checking to make sure our chosen image is available.

Ian:~$ docker images
REPOSITORY                     TAG                IMAGE ID       CREATED          SIZE
quay.io/biocontainers/iqtree   2.2.6-h21ec9f0_0   f3bc0d485009   4 months ago     49.7MB
quay.io/biocontainers/mafft    7.520--hec16e2b_0  3891f7c244e8   17 months ago    24.2MB

We can see that IQTREE is available, so let's run the image via Docker and make sure it's operating properly.

$ docker run -it f3bc0d485009

Here I specified that we want to run the image interactively -it and I've specified the image via its IMAGE ID.

If it ran properly, you should see your prompt changed and you are now inside the container.

sh-5.2#

Now we can test if the container is running properly. Run a common command, e.g. -help.

sh-5.2# iqtree -h

IQ-TREE multicore version 2.2.6 COVID-edition for Linux 64-bit built Dec  8 2023
Developed by Bui Quang Minh, James Barbetti, Nguyen Lam Tung,
Olga Chernomor, Heiko Schmidt, Dominik Schrempf, Michael Woodhams, Ly Trong Nhan.

Usage: iqtree [-s ALIGNMENT] [-p PARTITION] [-m MODEL] [-t TREE] ...

GENERAL OPTIONS:
  -h, --help           Print (more) help usages
  -s FILE[,...,FILE]   PHYLIP/FASTA/NEXUS/CLUSTAL/MSF alignment file(s)
...

Mounting a Directory

If we want to test a specific tool on local data (say for optimizing resources), we can follow the steps above. However, we'll need to make local data available within the container we want to test. That requires mounting the directory to the container so that Docker can make use of its files. You can find more info on mounting volumes on this docker.docs page.

We'll start by specifying that we want to --mount, then the kind of mount type=bind, identify the path to the directory src=<full/path>, then the target directory name within the container, and finally the IMAGE ID as above.

Ian:~$ docker run -t --mount type=bind,src=/Users/ian/test_alignments,target=/test_alignments f3bc0d485009

You should now be able to see that your chosen directory is mounted

sh-5.2# ls -lh

total 844K   
lrwxrwxrwx    1 root     root           7 Oct 17  2023 bin
drwxr-xr-x    2 root     root        4.0K Sep 29  2023 boot
drwxr-xr-x    5 root     root         360 Sep  3 09:22 test_alignments
...

You can check the contents of the mounted directory

sh-5.2# ls -lh test_alignments/

total 12M    
-rw-r--r--    1 root     root       91.5K Apr 30 12:12 A1CF.fasta
-rw-r--r--    1 root     root        3.4K May 17 10:20 AADAT.fasta
-rw-r--r--    1 root     root      109.8K May 17 10:21 RAG1.fasta
...

Lastly, we can run the actual image/program using those local files. The outputs will be written directly to the mounted directory.

sh-5.2# iqtree -s A1CF.fasta -T 2 -B 1000 -m GTR

IQ-TREE multicore version 2.2.6 COVID-edition for Linux 64-bit built Dec  8 2023
Developed by Bui Quang Minh, James Barbetti, Nguyen Lam Tung,
Olga Chernomor, Heiko Schmidt, Dominik Schrempf, Michael Woodhams, Ly Trong Nhan.

Host:    28fe6d389c70 (AVX2, FMA3, 11 GB RAM)
Command: iqtree -s A1CF.fasta -T 2 -B 1000 -m GTR
Seed:    187307 (Using SPRNG - Scalable Parallel Random Number Generator)
Time:    Tue Sep  3 09:28:56 2024
Kernel:  AVX+FMA - 2 threads (10 CPU cores detected)

Reading alignment file A1CF.fasta ... Fasta format detected
Reading fasta file: done in 0.0269167 secs using 99.05% CPU
Alignment most likely contains DNA/RNA sequences
Constructing alignment: done in 0.00883592 secs using 201.7% CPU
Alignment has 75 sequences with 1212 columns, 413 distinct patterns
390 parsimony-informative, 184 singleton sites, 638 constant sites
...

---

Singularity