-
Notifications
You must be signed in to change notification settings - Fork 5
10. Troubleshooting Containers
At one time or another we may run into issues with specific pieces of software and our own compute environment. When this happens we want to be able to see exactly what's happening with an individual program, and so we'll need to go back to basics and run the specific container/image that's causing trouble. Below I'll outline a couple use cases, such as checking that the image is installed, and troubleshooting on local files.
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)
...
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
...
Similar to Docker, Singularity/Apptainer works with containerized versions of software. It does not have a centralized command for telling you what images you currently have though (i.e. $ docker images). Because of this, we recommend storing singularity images in a consistent directory, by default, pipesnake will put these image fiels into $HOME/singularity_cache/, which makes it easier to keep an inventory.
Ian:~$ ls -lh singularity_cache/
total 2.6G
-rwxr-xr-x 1 root root 14M Feb 20 2024 biocontainers-raxml-8.2.9--h516909a_3.img
-rw-rw-r-- 1 root root 12M Jan 15 2024 depot.galaxyproject.org-singularity-aster-1.15--h4ac6f70_2.img
-rw-rw-r-- 1 root root 265M Jan 15 2024 depot.galaxyproject.org-singularity-iqtree-2.2.6--h21ec9f0_0.img
...
We can check that the image is working properly first:
Ian:~$ singularity exec depot.galaxyproject.org-singularity-iqtree-2.2.6--h21ec9f0_0.img 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)
...
If you're familiar with having to bind directories to give Docker access to access files, you'll be relieved to know you don't need to do the same with Singularity. Instead, Singularity should have access to all files available to the current user. We can check this by running a container in shell and then checking the file structure.
Ian:~$ singularity shell singularity_cache/depot.galaxyproject.org-singularity-mafft-7.520--hec16e2b_0.img
Singularity> ls -lh
total 11M
drwxr-xr-x 16 root root 172.0K Jul 15 21:34 Desktop
drwxr-xr-x 2 root root 4.0K Dec 21 2023 Documents
drwxr-xr-x 4 root root 4.0K Sep 2 16:16 Downloads
...