Scientific Computing and Data / High Performance Computing / Documentation / Running Container: Apptainer/Singularity

Apptainer/Singularity

On the Minerva HPC cluster, Apptainer (formerly known as Singularity) is the supported container runtime environment, known for its compatibility with high-performance computing (HPC) systems and enhanced security model. Unlike Docker, which requires root privileges and runs persistent daemons—posing potential security risks on multi-user HPC clusters—Apptainer was designed from the ground up to support secure, non-privileged container execution.

Although Docker is not available directly on Minerva for these reasons, existing Docker container images can be seamlessly converted and executed using Apptainer. This compatibility allows users to leverage the vast ecosystem of Docker containers while adhering to the stricter security and user access controls required on shared compute infrastructure.

Apptainer enables you to create and execute containers that encapsulate complex software environments into a single portable and reproducible image file (typically with a .sif extension). These images are self-contained, making them ideal for consistent and repeatable workflows across different environments.

You may choose to use Apptainer on Minerva when:

The software you need has complex dependencies that are difficult or impossible to install on your local machine or the HPC cluster.
The application requires newer kernel versions or system-level libraries that are not supported by the cluster’s operating system.
You need to reproduce a past analysis, share workflows with collaborators, or maintain long-term reproducibility of scientific pipelines.

Apptainer/Singularity Modules on Minerva HPC

Search for available Apptainer and Singularity Modules on Minerva:

How to use Apptainer/Singularity on Minerva HPC

Since Singularity and Apptainer share nearly identical command-line interfaces, the following sections will exclusively refer to Apptainer for consistency, but these commands are compatible with Singularity.

Load the apptainer module:

$ module load apptainer/1.3.6

You can use “apptainer pull” to download a container image from a give URI, such as pull the image from Sylabs Cloud library://, Singularity Hub shub:// and Docker Hub docker://

$ apptainer pull --name hello-world_latest.sif shub://vsoch/hello-world

To pull a docker image:

$ apptainer pull ubuntu_latest.sif docker://ubuntu:latest

To create a container within a writable directory (called a sandbox):

$ apptainer build --sandbox lolcow/ shub://GodloveD/lolcow

Running an Apptainer Container

When running within an Apptainer container, a user has the same permissions and privileges that he or she would have outside the container.

Once you have the images, you can shell into it (The shell subcommand is useful for interactive work)

# From the cluster
$ apptainer shell ubuntu_latest.sif

To run a container with the default runscript command:

$ apptainer run hello-world_latest.sif

Or run a custom command with exec, or pipes for batch processing (e.g. within a LSF job), For example:

$ apptainer exec ubuntu_latest.sif /path/to/my/script.sh

Where script.sh contains the processing steps to be executed within the LSF batch job. Alternatively, you can pass any standard Linux command directly to the exec subcommand. The exec subcommand also supports features like pipes and output redirection. Below is a simple example demonstrating a change in the Linux distribution environment:

Building External Directories

Binding a directory to your Apptainer container allows you to access files in a host system directory from within your container.

By default, /tmp, current working directory $PWD, user home directory $HOME, and /sc/arion/ is automatically mounted into an Apptainer container, which should be enough for most of the cases. You can also bind other directories into your Apptainer container yourself. To get a shell with a specified ‘dir’ mounted in the image.

$ apptainer run -B /user/specified/dir ubuntu_latest.sif

Warning: Sometimes libraries or packages in $HOME got picked up in container, especially for python packages at ~/.local and R library $_LIBS_USER at ~/.Rlib).

Running GPU-Enabled Containers

Apptainer supports running on GPUs from within containers. The --nv option must be passed to the exec or shell subcommand. For example:

$ module load apptainer/1.3.6 
$ apptainer pull docker://tensorflow/tensorflow:latest-gpu 
$ apptainer shell --nv -B /run tensorflow_latest-gpu-jupyter.sif

IMPORTANT:
Apptainer gives you the ability to install and run applications in your own Linux environment with your own customized software stack. While the HPC staff can provide guidance on how to create and use Apptainer containers, we do not have the resources to manage containers for individual users. If you decide to use Apptainer, it is your responsibility to build and manage your own containers, and software within your own Linux environment.

Building Your Own Containers

Although there are a lot of container images contributed by various users on Docker Hub and Singularity Hub, there is time that you want to create/build your own containers. You can build your own container images either use Singularity Remote Builder or your local Linux workstation with which you have the root access. If you don’t have a Linux system you could easily install one in a virtual machine using software like VirtualBox, Vagrant, VMware, or Parallels.

- Apptainer build is not fully supported on Minerva due to the sudo privileges for users
- Using the Remote Builder, you can easily and securely create containers for your applications without special privileges or set up in your local environment from a Linux machine where you have administrative access (i.e. a personal machine)
- Write your recipe file/definition file following the guide. You can easily find some examples for recipe files online, for example this GitHub repo.
- Convert a Dockerfile into a Singularity (now Apptainer) recipe file using spython — a Python-based tool to work with Singularity/Apptainer images and recipes.:
```
$ ml python 
$ spython recipe Dockerfile Singularity
```