Introduction to Apptainer

Note

Prerequisites

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

At face value, Apptainer is an alternative container implementation to Docker that has an overlapping set of features but some key differences as well. Apptainer 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 Apptainer runtime is compatible with Docker containers! So in general, we follow the practice of using Docker to develop containers and using Apptainer simply as a runtime to execute containers on HPC systems.

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

Login to Frontera

For today’s training, we will use the Frontera supercomputer, the 33rd 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 Apptainer module is currently only available on compute nodes at TACC. To use Apptainer 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 Apptainer Module

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

$ module list

$ module spider apptainer

$ module load tacc-apptainer

$ module list

Now the apptainer command is available.

$ type apptainer

$ apptainer help

Core Apptainer 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.

$ apptainer 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.

$ apptainer shell lolcow_latest.sif

Apptainer>

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 an Apptainer container, you are the same user as you are on the host system. Also, a number of host directories are mounted by default.

Apptainer> whoami

Apptainer> id

Apptainer> pwd

Apptainer> exit

Note

Docker and Apptainer have very different conventions around how host directories are mounted within the container. In many ways, Apptainer 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, Apptainer can run the default “entrypoint” or default command of a container with the run subcommand. These defaults are defined in the Dockerfile (or Apptainer Definition file) that define the actions a container should perform when someone runs it.

    $ apptainer 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, Apptainer 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:

    $ apptainer exec --cleanenv lolcow_latest.sif cowsay Apptainer runs Docker containers on HPC systems
 _______________________________________
/ Apptainer 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