Introduction to Singularity/Apptainer

Note

Prerequisites

This section uses the Frontera compute cluster to run Singularity. An active allocation on Frontera is required, though most content will apply to any system that supports Singularity.

At face value, Singularity is an alternative container implementation to Docker that has an overlapping set of features but some key differences as well. Singularity is commonly available on shared clusters, such as TACC’s HPC systems, because the Docker runtime is not secure on systems where users are not allowed to have “escalated privileges”. Importantly, the Singularity runtime is compatible with Docker containers! So in general, we follow the practice of using Docker to develop containers and using Singularity simply as a runtime to execute containers on HPC systems.

If you are familiar with Docker, Singularity will feel familiar.

Note

Singularity has rebranded itself as Apptainer, and they are the same software. At some point, the name of the executable will change as well, but this has not happened yet on all systems at TACC. For now, we will stick to calling it Singularity to avoid confusion. More info is here: https://apptainer.org/

Login to Frontera

For today’s training, we will use the Frontera supercomputer, the 21st most powerful system in the world at the time of the course. To login, you need to establish a SSH connection from your laptop to the Frontera system. Instructions depend on your laptop’s operating system.

Mac / Linux:

Open the application ‘Terminal’
ssh username@frontera.tacc.utexas.edu
(enter password)
(enter 6-digit token)

Windows:

If using Windows Subsystem for Linux, use the Mac / Linux instructions.
If using an application like ‘PuTTY’
enter Host Name: frontera.tacc.utexas.edu
(click ‘Open’)
(enter username)
(enter password)
(enter 6-digit token)

When you have successfully logged in, you should be greeted with some welcome text and a command prompt.

Start an Interactive Session

The Singularity module is currently only available on compute nodes at TACC. To use Singularity interactively, start an interactive session on a compute node using the idev command.

$ idev -m 40

If prompted to use a reservation, choose yes. Once the command runs successfully, you will no longer be on a login node, but instead have a shell on a dedicated compute node.

Load the Singularity Module

By default, the singularity command is not visible, but it can be added to the environment by loading the module.

$ module list

$ module spider singularity

$ module load tacc-singularity

$ module list

Now the singularity command is available.

$ type singularity

$ singularity help

Core Singularity Commands

Pull a Docker container

Containers in the Docker registry may be downloaded and used, assuming the underlying architecture (e.g. x86) is the same between the container and the host.

$ singularity pull docker://godlovedc/lolcow

$ ls

There may be some warning messages, but this command should download the latest version of the “lolcow” container and save it in your current working directory as lolcow_latest.sif.

Interactive shell

The shell command allows you to spawn a new shell within your container and interact with it as though it were a small virtual machine.

$ singularity shell lolcow_latest.sif

Singularity lolcow_latest.sif:~>

The change in prompt indicates that you have entered the container (though you should not rely on that to determine whether you are in container or not).

Once inside of a Singularity container, you are the same user as you are on the host system. Also, a number of host directories are mounted by default.

Singularity lolcow_latest.sif:~> whoami

Singularity lolcow_latest.sif:~> id

Singularity lolcow_latest.sif:~> pwd

Singularity lolcow_latest.sif:~> exit

Note

Docker and Singularity have very different conventions around how host directories are mounted within the container. In many ways, Singularity has a simpler process for working with data on the host, but it is also more prone to inadvertantly having host configurations “leak” into the container.

Run a container’s default command

Just like with Docker, Singularity can run the default “entrypoint” or default command of a container with the run subcommand. These defaults are defined in the Dockerfile (or Singularityfile) that define the actions a container should perform when someone runs it.

    $ singularity run lolcow_latest.sif

 ________________________________________
< The time is right to make new friends. >
 ----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Note

You may receive a warning about “Setting locale failed”. This is because, by default, Singularity sets all shell environment variables inside the container to match whatever is on the host. To override this behavior, add the --cleanenv argument to your command.

Executing arbitrary commands

The exec command allows you to execute a custom command within a container. For instance, to execute the cowsay program within the lolcow_latest.sif container:

    $ singularity exec --cleanenv lolcow_latest.sif cowsay Singularity runs Docker containers on HPC systems
 _______________________________________
/ Singularity runs Docker containers on \
\ HPC systems                           /
 ---------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Note

exec also works with the library://, docker://, and shub:// URIs. This creates an ephemeral container that executes a command and disappears.

Once you are finished with your interactive session, you can end it and return to the login node with the exit command:

$ exit