Singularity on Discovery¶
Singularity is the container runtime engine for the Discovery cluster and is installed as a module. With Singularity, you can run existing containers or pull and run your own custom container.
How to run a container with Singularity¶
You can run a container image with the run or exec commands after moving to a compute node and loading the singularity module.
To see available singularity versions run this in the command line: module avail singularity
Important
The --bind or -B flag
It’s important to mount the directories in the Discovery cluster to the container image so you can access necessary input data and to output the results of your software to the directory you specify.
For example, this command will allow you to access your directories on /work and /scratch while running the container.
-B “/work:/work,/scratch:/scratch”
Example using an image already located on the file system¶
We have several container images located in /shared/container_repository
Here’s an srun example using a singularity image from the /shared/container_repository
srun --pty /bin/bash
module load singularity/3.10.3
singularity run -B "/work:/work" /shared/container_repository/star/star_2.7.8a.sif
Singularity>
Singularity> STAR
Usage: STAR [options]... --genomeDir /path/to/genome/index/ --readFilesIn R1.fq R2.fq
Spliced Transcripts Alignment to a Reference (c) Alexander Dobin, 2009-2020
STAR version=2.7.8a
STAR compilation time,server,dir=Wed Nov 15 00:19:03 UTC 2023 f81ff285a72e:/opt/STAR-2.7.8a/source
For more details see:
<https://github.com/alexdobin/STAR>
<https://github.com/alexdobin/STAR/blob/master/doc/STARmanual.pdf>
To list all parameters, run STAR --help
An example sbatch script
#!/bin/bash
#SBATCH --nodes=1
#SBATCH --time=01:00:00
#SBATCH --partition=short
#SBATCH --job-name=star
#SBATCH --output=star.out
#SBATCH --error=star.err
#SBATCH --ntasks=1
module load singularity/3.10.3
cd /work/mygroup
singularity exec -B "/work:/work" /shared/container_repository/star/star_2.7.8a.sif STAR \
--genomeDIR /path/to/genome \
--readFilesIn R1.fq R2.fq
Pull an image from a URL¶
with the command singularity pull you can pull an existing container image from the repositories listed below:
Important
The Importance of Tags and Scientific Reproducibility
Container images are cataloged using “tags”. The tag can indicate the version of the image build or some other aspect of the image. Common tags include “latest” and will pull the most recent version of the image. Care should be taken to distinguish the container version from the version of the software installed, as the same tag on a container image (i.e., “latest”) will pull different versions of software over time. We recommend pulling specific versions of images to better track the version used.
Example pulling Spades image from Dockerhub¶
We’ll use a compute node with the InfiniBand network to pull the image. The process of pulling an image and converting it to singularity format (.sif) will take longer for large images.
More about the spades metagenome assembler image can be found here.
srun --constraint=ib -p short --pty /bin/bash
module load singularity/3.10.3
cd /work/groupname/container_images
mkdir -p cache tmp
export SINGULARITY_CACHEDIR=$(pwd)/cache
export SINGULARITY_TMPDIR=$(pwd)/tmp
singularity pull spades_3.15.5.sif docker://staphb/spades:3.15.5
# This will pull an image which will be named spades_3.15.5.sif
# There will be several warnings (warn xattr{}) which can be ignored
# Test the container with singularity run remember to use the "-B" flag to bind any directories
singularity run spades_3.15.5.sif
Singularity> spades.py --test
This container image can now be used as in the srun and sbatch examples above.
Note
Pulling container images to the Discovery cluster can contribute to your storage use in /home. If a cache and tmp directory aren’t created and exported as in the example above, these items will be deposited in a hidden directory in your home at .singularity.
Please check your home storage usage regularily to stay below the quota. See Home Directory Storage Quota for more.