Singularity and Docker Containers
Contents
Overview
Singularity is open source containerization software that can be used on Matilda as a potential alternative to Docker. Whereas Docker utilizes a daemon (service) running as root in the background (and as such, is not secure), Singularity runs standalone in client-mode, and is preferred by HPC environments like Matilda. This document presents a brief overview of how to use Docker images with Singularity on Matilda, with a few examples.
Running a Docker Image in Singularity
Many developers of open source software offer Docker containers of their applications. These are particularly popular with pipeline analysis and simulation systems. In many cases, it is possible to simply pull a Docker container and run it in Singularity directly, without running Docker.
One example is the application pipeline "Deep Variant" (which is also available on Matilda). To create and run the Docker image in Singularity (creating a *.sif) file, one only needs:
module load Singularity singularity pull docker://google/deepvariant:"1.5.0"
In this case, we simply load the Singularity modulefile, and pull the Docker image down. This will create a Singularity file named "deepvariant_1.5.0.sif", which can then be run with standard Singularity commands and file mount points. For instance:
singularity run -B /usr/lib/locale/:/usr/lib/locale/ -B /scratch/users/someuser/:$(pwd) $DV_HOME/deepvariant.sif /opt/deepvariant/bin/run_deepvariant --model_type=WGS \ --ref=quickstart-testdata/ucsc.hg19.chr20.unittest.fasta --reads=quickstart-testdata/NA12878_S1.chr20.10_10p1mb.bam --regions "chr20:10,000,000-10,010,000" \ --output_vcf=quickstart-output/output.vcf.gz --output_gvcf=quickstart-output/output.g.vcf.gz --num_shards=1
While this KB is not intended to provide a detailed explanation of Singularity usage, for clarity, the command above is mapping external:internal mount points (denoted with the -B flag). So here, the directory "/scratch/users/someuser" (external filesystem) is mapped to "$(pwd)" - the internal (i.e. within the Singularity container) run directory (known in Docker as an "entry point".
Building a Singularity Image from Docker
While it is not possible to directly build a Singularity image from a Docker container, one can be created by first generating (and modifying as needed) a "definition file" (*.def) from the Docker container. Alternately, if a definition file is available, a Singularity image can be created from that. For example, if you have a Dockerfile it is possible to create a Singularity definition file by "translating" the Dockerfile to match your system characteristics. While there isn't a cookbook method for doing this, such a translation could be as simply as changing "apt-get install" (Ubuntu systems) to "yum install" (RedHat systems). You will be restricted however, if you are not root and are trying to install packages where root privileges are required.
Once you have a definition file, a Singularity image can be built using the following:
module load Singularity singularity build mysingularity.sif mysingularity.def
Running a Singularity Container on Matilda
Interactively
One obvious way to use Singularity would be to launch an interactive job on one of the nodes, load Singularity, and then run the container. For instance:
srun -N 1 -n 1- -t 4:00:00 --pty /bin/bash module load Singularity singularity run ....
This would obviously work best for containers which are designed to be interactive with respect to input and output. But could also be used for run-and-forget scenarios, although batch mode would probably be more efficient as discussed below.
As a Batch Job
Simply create a job script where the desired resources are requested, Singularity is loaded as a modulefile, and the Singularity command desired is executed (the SLURM resource manager can accommodate Singularity runs):
## Example batch file #!/bin/bash #SBATCH -N 1 #SBATCH --ntasks=10 #SBATCH --time=4:00:00 module load Singularity singularity run ....
More Information
CategoryHPC