Apptainer – Quickstart Guide

Apptainer, formerly known as Singularity, is an open-source container platform designed to facilitate the deployment of complex applications on high-performance computing (HPC) clusters. It provides a simple, portable, and reproducible method for running applications, allowing researchers to execute scientific programs without the need for native installation by cluster administrators.

Understanding Containers

Basic Concepts of Containerization

Containerization is a method of packaging software so that it can run with its dependencies in isolated environments called containers. These containers are lightweight and include everything needed to run the application: code, runtime, system tools, libraries, and settings.
This technology allows developers to easily deploy applications across different computing environments, from a developer’s laptop to a test environment, from a staging environment into production, and from a physical machine in a data center to a virtual machine in a public or private cloud.

Difference Between Containers and VM’s

Containers and Virtual Machines (VMs) are both technologies used to create efficient, isolated environments for running applications, but they operate differently.
A container encapsulates an application’s code along with its libraries, dependencies, and some lightweight operating system APIs and services, all running on the host’s operating system kernel. This makes containers highly portable and efficient, as they are smaller in size and require less overhead than VMs.
On the other hand, a VM includes a full copy of an operating system, including its own kernel, on top of a hypervisor which runs on the physical hardware. This means each VM is entirely isolated with its own resources, but this also results in greater resource consumption compared to containers.

Use Cases for Containers in Scientific Computing

Containers have several use cases for scientific computing:

• Reproducibility: Containers help ensure that scientific computations are reproducible across different computing environments. By packaging software with all its dependencies, researchers can share their containers with others, knowing that their software will run the same way everywhere.
• Collaboration: Containers facilitate collaboration among communities by providing a consistent environment that can be used across various systems. This is particularly useful in large, distributed teams working on complex projects.
• Portability: Containers allow applications to be easily moved from one computing environment to another, such as from a local machine to an HPC cluster, without the need for reconfiguration.

Setup

Loading Apptainer

To be able to use the apptainer command, you must first load the apptainer module.

$ module load apptainer

To verify that the command was loaded successfully, you can use the following command to see what version of Apptainer is being used.

$ apptainer ‐‐version
apptainer version 1.2.4+318-g636ab8526

Changing the Apptainer Cache Directory

By default, Apptainer creates a download cache in the directory $HOME/.apptainer/cache. For people running Apptainer on a personal PC, that typically isn’t an issue. However, since the cache directory can grow very rapidly, it’s recommended to move the cache directory to a different directory such as your /scratch directory to prevent going over quota.

The Apptainer documentation tells us that the bash environment variable APPTAINER_CACHEDIR controls where the cache directory is located. To change the cache directory to somewhere such as /scratch/abc123/apptainer_cache for your current session, you would use the following command:

$ export APPTAINER_CACHEDIR=/scratch/abc123/apptainer_cache

To make the changes persistent, add the command above to your ~/.bashrc file, then load it into your current shell.

$ echo "export APPTAINER_CACHEDIR=/scratch/abc123/apptainer_cache" >> ~/.bashrc
$ source ~/.bashrc

Running Containers on the HPC Cluster

Downloading Containers

To download a container, you can use the apptainer pull command.

$ apptainer pull [options] [url]

Some common options include:

• ‐‐dir [directory]: Directory to place the downloaded container file. Defaults to the current directory.
• ‐‐disable-cache: Prevents Apptainer from creating cached files of the downloaded container. The purpose of download cache is to speed up downloads by downloading only what’s not in the cache, and this flag will mean you have to download the files every time you’re downloading a container.

For the [url] part of the command, you will need to prepend the container tag with the source of where you’re downloading your container from. Valid entries listed on the Apptainer documentation include:

• library://[container:tag]
• docker://[image:tag] (Docker Hub)
• shub://[image:tag] (Singularity Hub)
• oras://[image:tag] (OCI registry that supports ORAS)
• https://[url]/[image].sif (SIF file from a custom URL)

Example:

$ apptainer pull --dir /scratch/abc123/ docker://deeplabcut/deeplabcut:latest-gui

Note: If you are downloading a container image that isn’t in a Singluarity container format (SIF), then Apptainer will automatically convert the image to a SIF image, which may take a bit of time depending on the image.

Note: If you haven’t configured your cache directory or did not include the ‐‐disable-cache flag, then your command may be cancelled due to going over your disk quota. See Changing the Apptainer Cache Directory for instructions on how to change this directory.

Once you have downloaded the container, you can see that the image has been placed into a file.

$ ls /scratch/abc123/
deeplabcut_latest-gui.sif

Running a Container

Each container may have a specific method to run a given container, so it’s best that you primarily refer to the documentation for that given image. However, it’s important to keep in mind that commands for other container solutions such as Docker will not work with Singularity, and will require you to use some intuition and trial-and-error in order to convert the commands and arguments over to Apptainer.

Generally, to run a container, you would use the apptainer run command.

$ apptainer run [options] [image]

There are many possible configuration options available for this command, so you may want to run the command apptainer run ‐‐help to view all the available options. However, some general important ones include:

• -c: Contains the filesystem in the container to a bare minimum. Without the flag, the host OS filesystem is attached to the container.
• ‐‐fakeroot: Runs the container as root. This root user is isolated within the container and contains root privileges only for user’s/filesystems/programs inside the container. This is not a workaround to be able to use sudo on Monsoon for anything, but it can be useful for operations such as package management inside a container of an operating system such as Ubuntu.
• ‐‐nv: Attaches an NVIDIA GPU to the container. This is required for GPU workloads.

The [image] paramater is interesting in that it can take either a .sif image file OR a web image link, such as shown in the Downloading Containers section. If you give it a web image link, then Apptainer will download the image and run it without saving it to the filesystem.

Examples:

$ apptainer run --nv /scratch/abc123/deeplabcut_latest-gui.sif
$ apptainer run --nv docker://deeplabcut/deeplabcut:latest-gui

Additional Resources

This page only covers the basics on how to get a simple Apptainer container up and running, but there is still much more you can do with it! If you wish to learn more about how to use Apptainer, check out the Apptainer user documentation.