Singularity - Docker on the HPC#
Singularity is a container platform. It allows you to create and run containers that package up pieces of software in a way that is portable and reproducible.
You can build a container using Singularity on your laptop, and then run it on the HPC
What is a container?#
Containers are a software deployment process that bundles an application’s code along with all the files and libraries it needs to run in a single file.
When time comes to run the image, there’s nothing to intall or configure, it just works.
This improves it’s portability significantly and makes reproducing others research much easier.
You can find the documentation for singularity here: https://docs.sylabs.io/guides/main/user-guide/
Accessing Containers#
Singularity uses containers which consist of a file, ending in sif, that you can copy to the cluster using SCP through program like WinSCP.
You can also download a container from a library called a hub. A popular hub is the Docker Hub (https://hub.docker.com/explore/).
To pull a container from a hub you can use the ‘singularity pull’ command.
Here’s an example to pull a version of ubuntu from docker:
singularity pull docker://ubuntu:18.04
A file called ubuntu_18.04.sif will be downloaded.
Running a Container#
There are a number of ways to run a container, but the primary way on a HPC is to run it via a batch script.
You can also run it on the login node, but this should only be for testing. Heavy computation should be avoided.
Here are some examples on how to use a singularity container
Using the ‘exec’ command
The exec command allows you to execute a command within your container.
For example, if we run:
cat /etc/os-release
outside our container, we get the output:
NAME="Rocky Linux"
VERSION="8.7 (Green Obsidian)"
However running the same command in the container:
Singularity exec ubuntu_18.04.sif cat /etc/os-release
we get the following output:
PRETTY_NAME="Ubuntu 23.04"
NAME="Ubuntu"
VERSION_ID="23.04"
VERSION="23.04 (Lunar Lobster)"
Use the ‘run’ command
The run command executes a containers run-script. The run script was set by the creator when the container was built.
In the case of the Ubuntu container we downloaded, the script simply starts a shell within it.:
Singularity run ubuntu_18.04.sif
Running the container like you would a program will also execute the run-script:
./ubuntu_18.04.sif
Use the ‘shell’ command
The shell command invokes an interactive shell within the container:
Singularity shell ubuntu_18.04.sif
Here we will run cat /etc/os-release in the ubuntu shell:
[padmacor@loginhpc ~]$ singularity shell ubuntu_18.04.sif
Singularity> cat /etc/os-release
NAME="Ubuntu"
VERSION="18.04.6 LTS (Bionic Beaver)"
ID=ubuntu
ID_LIKE=debian
PRETTY_NAME="Ubuntu 18.04.6 LTS"
Singularity>
Notice that the prompt changes to Singularity so you know you are using the containers shell.
File Access
When you use a container you run within the container’s environment. The directories available to you by default from the host environment are:
your home directory
working directory (directory you were in when you ran the container)
/tmp
Singularity and Slurm#
Here’s a simple script for running a container as a batch job:
#!/bin/bash
#SBATCH --job-name=singularity_test # Job name
#SBATCH --mail-type=END,FAIL # Mail events(NONE,BEGIN,END,FAIL,ALL)
#SBATCH --mail-user=email@lshtm.ac.uk # Where to send mail
#SBATCH --time=00:05:00 # Time limit hrs:min:sec
#SBATCH --ntasks=1 # Run on a single core
#SBATCH --mem=1gb # Job memory request
# Singularity command line options
module load singularity
singularity exec ubuntu_18.04.sif cat /etc/os-release
Where to build Singularity Images#
To build a singularity container, you need root access to the build system.
Therefore you can’t build a singularity container on the HPC.
There are a number of options for building contatiners on other systems.
You can then move them to the HPC once built.
Another Linux System
If you have a Linux system for which you have root access, you can install singularity and build your containers there.
You can find a guide on installing it here: https://docs.sylabs.io/guides/3.1/user-guide/installation.html#install-on-linux
On Windows
You can build a singularity image from a docker image with the docker2singluarity docker image: https://hub.docker.com/r/singularityware/docker2singularity
A Virtual Machine
If you don’t have a Linux computer, you can download software like VMWare Workstation or VirtualBox
Install Linux there, then follow the above instructions to install singularity.
How to build Singularity images#
To build a container the first thing you need is a definition file. This defines the software configuration of the container you will create.
Here is an example of a simple ubuntu container with a simple hello world run-script:
Bootstrap: docker
From: ubuntu:18.04
%help
This is an Ubuntu 18.04 Singularity container.
%post
apt-get -y update && apt-get install -y python
%runscript
python -c 'print("Hello World! Hello from our custom Singularity image!")'
The first two lines in our definition file define where to bootstrap our image from.
The Bootstrap: docker line is similar to where we used docker:// earlier with the singularity pull command and means we want to pull bootstrap image from the Docker Hub.
The second line specifies that we want to use the Ubuntu image with the tag 18.04, which in this case is the OS version.
After that we have a number of section specified by using the % prefix. Here we only use the %post and %runscript sections.
In the %post section we do tasks like package installation, adding extra data and configuring the OS.
Next is the %runscript section where we set a script to run when the container is executed. For the example we print a statement to standard out.
Now we can save the definition file, we’ll call it test.def. It can be built with the command:
singularity build /home/padmacor/test.sif /home/padmacor/test.def
A container will be created with the name test.sif
More information about definition files and sections can be found here: https://docs.sylabs.io/guides/3.8/user-guide/definition_files.html