Using containers

About Apptainer

Apptainer is a 'container framework' that is used to run software that needs to have a different runtime environment than that provided by the operating system. When you run the container, the container environment takes over from the 'host' operating system and replaces the contents of the root (/) diretory from the host with its own version, which might be very different from that on the host. For example, the cluster runs Red Hat whereas a container might run Ubuntu.

Apptainer should be capable of running both containers built with the native apptainer program as well as those built with singularity. We will use 'apptainer' to mean either hereafter. Below we provide examples of some of the most common ways you might use apptainer. For complete documentation, see the official Apptainer User Guide.

Cache folders

Apptainer will cache container images generated from remote sources, and any layers used to create them. The cache is created at $HOME/.apptainer/cache by default. Since our $HOME directory space is more limited than other storage spaces (e.g., /tmp or /gpfs2), you may wish to change the cache location. This can be changed by changing the location of the cache by creating a directory and setting the APPTAINER_CACHEDIR environment variable to it. For example,

$ mkdir $HOME/scratch/apptainer-cache
$ export APPTAINER_CACHEDIR=$HOME/scratch/apptainer-cache

Note that you only create the directory once, but the variable must be set before your run apptainer for the first time in each session. You can add the export command above to your $HOME/.bashrc file so it is set automatically for each session.

Ways to use containers

There are three ways to access the software included in a container: using the 'run script', executing a command from inside the container, or using a shell that is inside the container. We provide an example container at /gpfs1/sw/examples/containers/example.sif with which we will illustrate usage. It can be convenient to define a variable with the full path to the container to make subsequent commands shorter. The examples that follow assume you have run this command.

$ export SIF=/gpfs1/sw/examples/containers/example.sif

We recommend that you always use the -e option to that variables and functions on the VACC host are not defined inside the container.

Using the container's run script

Many -- but not all -- containers will have a script in them that may be the container creator's preferred way to run the containerized programs. You definitely want to consult the container's documentation to see whether that is the case. Sometimes the run script will just set up the environment for the programs inside the container, other times it will execute a command, and sometimes it basically does nothing.

Our example container has a run script that can take optional arguments. To run it most simply, use

$ apptainer run -e $SIF
$ apptainer run -e $SIF "-e -f some options"

Executing a single command from the container

You can also run an executable program from within the container.

$ apptainer exec -e $SIF cat /etc/lsb-release

Using a shell from inside the container

A special case of running a program from within the container is to run a regular shell, usually bash. The prompt will change to an Apptainer> prompt, at which you can type any commands that are valid inside the container.

$ apptainer shell -e $SIF
Apptainer> echo "Hello out there!"

Using a script outside the container

$ apptainer exec /path/to/container /path/to/script/on/host

Building containers on the cluster

$ apptainer build <container_name.sif> <source for building>

You can create a container within a writable directory (called a sandbox) using the --sandbox option.

$ apptainer build --sandbox <directory_name>/ <source for building>

The resulting directory operates just like a container in a SIF file. To make persistent changes within the sandbox, use the --writable flag when you invoke your sandboxed container.

$ apptainer shell --writable <sandbox_directory_name>

You can also use the --writable option to shell into a sif container file.

$ apptainer shell --writable <container_name.sif>

Special cases

If you have a container that will not build without using the –-fakeroot option, please send e-mail to vacchelp@uvm.edu and tell us the circumstances.