Singularity - Linux Containers

The Wynton cluster supports Linux containers via the Singularity software. A Linux container is an efficient and powerful virtualization method for running isolated Linux systems (“containers”) on any Linux system including CentOS used by our cluster.

Singularity, and Linux containers in general, provides solutions to common problems and hurdles that HPC users often face, e.g.

Because you can create and customize your own containers, and because Singularity also supports Docker containers, you have immediate access to a very large number of Singularity and Docker containers available via repositories such as:


All tasks for using Linux containers, such as downloading, building, and running containers, is done via the singularity client and supported on Wynton. The most common command calls are:

For full details, see singularity --help, man singularity, and the Singularity website.


Building a container

As an illustration on how to use Linux containers with Singularity, we will use the Docker container rocker/r-base available on Docker Hub. This particular container provides the latest release of the R software in an Ubuntu OS environment. Containers available from Singularity Hub, Biocontainers, and elsewhere, can be downloaded and used analogously.

To use this rocker/r-base container, we first pull it down to a Singularity image file ~/lxc/rocker_r-base.img as:

[alice@dev3 ~]$ mkdir lxc
[alice@dev3 ~]$ cd lxc/
[alice@dev3 lxc]$ singularity build rocker_r-base.img docker://rocker/r-base
INFO:    Starting build...
Getting image source signatures
Copying blob sha256:6359bcfdcac7731506d8e89a85e5882f23711354ffe717d8228087cfd6a31fc3
 48.65 MiB / 48.65 MiB [====================================================] 2s
Copying blob sha256:7921cd62653e41062bfc021b7d7475b4a8ff16cb249a4c29974d0d010635d591
 1.80 KiB / 1.80 KiB [======================================================] 0s
Copying blob sha256:d835b7b583179a707477a96f6e35248894a2effed6af535b01e88e24f051a273
 25.93 MiB / 25.93 MiB [====================================================] 1s
Copying blob sha256:7d1e021b0f81cdcc447f012b462c892a3573a2d879c5b01493367d089cf60782
 842.65 KiB / 842.65 KiB [==================================================] 0s
Copying blob sha256:8e435d138f2bba19b6f85a2f3ef301f4a5d65bdc16ff417b746f9e926e738741
 297 B / 297 B [============================================================] 0s
Copying blob sha256:93d86fef617f6bd75b377f72981c7e8e28113020154f98e121942de5f828d591
 199.05 MiB / 199.05 MiB [==================================================] 7s
Copying config sha256:58ff9f07c993587fd9c31743c22bc4422852eae0b47a8b0d9b5e10e966f8db0d
 3.72 KiB / 3.72 KiB [======================================================] 0s
Writing manifest to image destination
Storing signatures
2019/10/31 17:09:37  info unpack layer: sha256:6359bcfdcac7731506d8e89a85e5882f23711354ffe717d8228087cfd6a31fc3
2019/10/31 17:09:40  info unpack layer: sha256:7921cd62653e41062bfc021b7d7475b4a8ff16cb249a4c29974d0d010635d591
2019/10/31 17:09:40  info unpack layer: sha256:d835b7b583179a707477a96f6e35248894a2effed6af535b01e88e24f051a273
2019/10/31 17:09:41  info unpack layer: sha256:7d1e021b0f81cdcc447f012b462c892a3573a2d879c5b01493367d089cf60782
2019/10/31 17:09:41  info unpack layer: sha256:8e435d138f2bba19b6f85a2f3ef301f4a5d65bdc16ff417b746f9e926e738741
2019/10/31 17:09:41  info unpack layer: sha256:93d86fef617f6bd75b377f72981c7e8e28113020154f98e121942de5f828d591
INFO:    Creating SIF file...
INFO:    Build complete: rocker_r-base.img

[alice@dev3 lxc]$ ll rocker_r-base.img
-rwxr-xr-x. 1 alice lsd 271249408 Oct 31 17:09 rocker_r-base.img

The above may take a minute or two to complete.

Running a container

After this, we can run R within this container using:

[alice@dev3 lxc]$ singularity run rocker_r-base.img

R version 3.6.1 (2019-07-05) -- "Action of the Toes"
Copyright (C) 2019 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

  Natural language support but running in an English locale

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> sum(1:10)
[1] 55
> q()
Save workspace image? [y/n/c]: n
[alice@dev3 lxc]$ 

Exactly what is “run” is defined by the so called “runscript” of the Singularity container, or the “CMD” if imported from a Docker container. An alternative way to launch R within this container is by explicitly executing R, e.g.

[alice@dev3 lxc]$ singularity exec rocker_r-base.img R --quiet
> sum(1:10)
[1] 55
> q("no")
[alice@dev3 lxc]$ 

Note that, the Singularity image is marked as an executable, which means you can run it as any other executable, e.g.

[alice@dev3 lxc]$ ./rocker_r-base.img

R version 3.6.1 (2019-07-05) -- "Action of the Toes"
Copyright (C) 2019 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

> sum(1:10)
[1] 55
> q("no")
[alice@dev3 lxc]$ 								

To launch a shell within this container, and to also convince yourselves that the container runs Ubuntu (and not CentOS as on the Wynton host system), do:

[alice@dev3 lxc]$ singularity shell rocker_r-base.img
Singularity rocker_r-base.img:~/lxc> head -3 /etc/os-release
PRETTY_NAME="Debian GNU/Linux buster/sid"
NAME="Debian GNU/Linux"
Singularity r-base.img:~/lxc> Rscript --version
R scripting front-end version 3.6.1 (2019-07-05)
Singularity r-base.img:~/lxc> exit

[alice@dev3 lxc]$ head -3 /etc/os-release
NAME="CentOS Linux"
VERSION="7 (Core)"

Running a container as a job

When it comes to the scheduler, there is nothing special about Singularity per se - the Singularity software can be used as any other software on the cluster. As a proof of concept, here is how to calculate the sum of one to ten using R within the above Linux container at the command line:

[alice@dev3 ~]$ singularity exec rocker_r-base.img Rscript -e "sum(1:10)"
[1] 55
[alice@dev3 ~]$

and here is how to do the same via the job scheduler:

[alice@dev3 ~]$ echo 'singularity exec rocker_r-base.img Rscript -e "sum(1:10)"' | qsub -cwd -j yes -N r-base
Your job 5570948 ("r-base") has been submitted
[alice@dev3 ~]$ cat r-base.o5570948
[1] 55


Q. Why not Docker?
A. Docker is one of the most popular and well-known software solutions for using Linux Containers. However, contrary to Singularity, it turns out that it is hard to get Docker to play well with multi-tenant HPC environments.

Q. What’s the difference between *.img and *.simg?
A. The filename extension of Singularity images are optional, but using one helps clarify that an executable is a Singularity image. The *.img indicates a writable (ext3) images whereas *.simg indicates a read-only (squashfs) image.