Containerized software#

Containerization is a technique for running jobs in an isolated and reproducible manner, by bundling all necessary dependencies up to and including entire operating systems and running the software using virtualization.

The Esrum cluster supports two different methods for running containerized software:

  1. Singularity (now renamed to AppTainer) for running containerized applications using the SLURM queuing system. Instructions are provided below for converting existing Docker/Podman containers.

  2. Podman for longer-running services on the specialized container node. Podman is Docker compatible, but is designed from the ground up for running in user-space and therefore offers better security guarantees.

Singularity containers#

Singularity is available via Software on Esrum and allows you to run containerized software as part of Slurm jobs. If possible, you should prefer to run your containerized tools in this manner.

The following only covers the absolute basics. For more information please refer to the official Singularity documentation.

Running Docker Hub images#

Container images available on Docker Hub can be converted to singularity images in one step using the singularity build command. For the following example, we will download and run version 0.7.17 of the pegi3s/bwa image on Docker Hub:

$ module load --auto singularity
$ singularity build --disable-cache pegi3s_bwa_0.7.17.sif docker://pegi3s/bwa:0.7.17

This fetches the pegi3s/bwa image with the tag 0.7.17 and saves it to the local file pegi3s_bwa_0.7.17.sif. It is recommended that you save such images in the /apps folders of the project you are working on so that your collaborators can also access it.

The --disable-cache option is optional but recommended, since Singularity will otherwise cache the individual parts of the image it downloaded in ~/.singularity. As described in Data storage on Esrum your home is limited to 100 GB and larger docker images can easily take up gigabytes of space.

Once you have run the build command, the image can be run using the singularity run command:

$ singularity run pegi3s_bwa_0.7.17.sif bwa

Program: bwa (alignment via Burrows-Wheeler transformation)
Version: 0.7.17-r1188
Contact: Heng Li <lh3@sanger.ac.uk>

It is also possible to run Docker Hub images "directly" by using a docker:// URL instead of the path to a singularity image:

$ singularity run docker://pegi3s/bwa:0.7.17 bwa

However, this caches the image in your home folder, and it is therefore not recommended for the reasons described above.

Running custom Docker/Podman images#

Docker/Podman images run on another system must be exported and converted before they can be run on Esrum. The podman save and the corresponding docker save command may be used to export an image to a single file:

$ podman save my-image:v1.2.3 --output ~/my_image_v1.2.3.tar

Once the image has been exported, you can transfer it to Esrum using scp or another suck method:

$ scp ~/my_image_v1.2.3.tar abc1232@esrumhead01fl.unicph.domain:/projects/my_project/scratch/

Finally, you can convert the image on Esrum to the format used by singularity:

$ ssh abc123@esrumhead01fl.unicph.domain
$ module load --auto singularity
$ cd /projects/my_project/scratch/
$ singularity build my_image _v1.2.3.sif docker-archive://my_image_v1.2.3.tar

The singularity image can then be run using the singularity run command:

$ singularity run my_image_v1.2.3.sif

Podman containers#

The esrumcont01fl node is dedicated to running containerized software that is not suitable for conversion to/running via Singularity. Please Contact us if you wish to run containers on the container node.