Skip to content

Apptainer Container

Apptainer is a container platform. It allows you to create and run containers that package up pieces of software in a way that is portable and reproducible. You can build a container using Apptainer on your laptop, and then run it on many of the largest HPC clusters in the world, local university or company clusters, a single server, in the cloud, or on a workstation down the hall. Your container is a single file, and you don’t have to worry about how to install all the software you need on each different operating system.

Using Docker Images

Apptainer can import, bootstrap, and even run Docker images directly from Docker Hub. You can easily run an CentOS container like this:

$ cat /etc/redhat-release
CentOS Linux release 7.9.2009 (Core)
$ ml apptainer
$ apptainer shell docker://centos:latest
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
Getting image source signatures
Copying blob a1d0c7532777 done
Copying config 8c1402b22a done
Writing manifest to image destination
Storing signatures
2023/01/17 12:55:08  info unpack layer: sha256:a1d0c75327776413fa0db9ed3adcdbadedc95a662eb1d360dad82bb913f8a1d1
2023/01/17 12:55:09  warn rootless{usr/bin/newgidmap} ignoring (usually) harmless EPERM on setxattr "security.capability"
2023/01/17 12:55:09  warn rootless{usr/bin/newuidmap} ignoring (usually) harmless EPERM on setxattr "security.capability"
2023/01/17 12:55:09  warn rootless{usr/bin/ping} ignoring (usually) harmless EPERM on setxattr "security.capability"
2023/01/17 12:55:10  warn rootless{usr/sbin/arping} ignoring (usually) harmless EPERM on setxattr "security.capability"
2023/01/17 12:55:10  warn rootless{usr/sbin/clockdiff} ignoring (usually) harmless EPERM on setxattr "security.capability"
INFO:    Creating SIF file...
Apptainer> cat /etc/redhat-release
CentOS Linux release 8.4.2105

In this case, the image is downloaded from Docker Hub, extracted to a temporary directory, and Apptainer interactive shell is invoked. This procedure can take a lot of time, especially with large images.

Importing Docker Image

Apptainer containers can be in three different formats:

  • read-only squashfs (default) - best for production
  • writable ext3 (--writable option)
  • writable (ch)root directory (--sandbox option) - best for development

Squashfs and (ch)root directory images can be built from Docker source directly on the cluster, no root privileges are needed. It is strongly recommended to create a native Apptainer image to speed up the launch of the container.

$ ml apptainer
$ apptainer build ubuntu.sif docker://ubuntu:latest
INFO:    Starting build...
Getting image source signatures
Copying blob 6e3729cf69e0 done
Copying config 415250ec06 done
Writing manifest to image destination
Storing signatures
2023/01/17 12:58:04  info unpack layer: sha256:6e3729cf69e0ce2de9e779575a1fec8b7fb5efdfa822829290ab6d5d1bc3e797
INFO:    Creating SIF file...
INFO:    Build complete: ubuntu.sif

alternatively, you can create your own docker image and import it to Apptainer. For example, we show how to create and run ubuntu docker image with gvim installed:

your_local_machine $  docker pull ubuntu
your_local_machine $  docker run --rm -it ubuntu bash
# apt update
# apt install vim-gtk
your_local_machine $  docker ps -a
your_local_machine $  docker commit 837a575cf8dc
your_local_machine $  docker image  ls
your_local_machine $  docker tag 4dd97cefde62 ubuntu_gvim
your_local_machine $  docker save -o ubuntu_gvim.tar ubuntu_gvim

copy the ubuntu_gvim.tar archive to IT4I supercomputers, convert to Apptainer image and run:

$ ml Apptainer
$ apptainer build ubuntu_givm.sif docker-archive://ubuntu_gvim.tar
$ apptainer shell -B /usr/user/$ID ubuntu_gvim.sif

Note the bind to /usr/user/$ID directory.

Launching the Container

The interactive shell can be invoked by the apptainer shell command. This is useful for development purposes. Use the -w | --writable option to make changes inside the container permanent.

$ apptainer shell ubuntu.sif

Apptainer> cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=22.04
DISTRIB_CODENAME=jammy
DISTRIB_DESCRIPTION="Ubuntu 22.04.1 LTS"

A command can be run inside the container (without an interactive shell) by invoking the apptainer exec command.

$ apptainer exec ubuntu.sif cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=22.04
DISTRIB_CODENAME=jammy
DISTRIB_DESCRIPTION="Ubuntu 22.04.1 LTS""

An Apptainer image can contain a runscript. This script is executed inside the container after the apptainer run command is used. The runscript is mostly used to run an application for which the container is built. In the following example, it is the fortune | cowsay command:

$ apptainer build lolcow.sif docker://ghcr.io/apptainer/lolcow
INFO:    Starting build...
Getting image source signatures
Copying blob 5ca731fc36c2 skipped: already exists
Copying blob 16ec32c2132b skipped: already exists
Copying config fd0daa4d89 done
Writing manifest to image destination
Storing signatures
2023/01/17 13:06:01  info unpack layer: sha256:16ec32c2132b43494832a05f2b02f7a822479f8250c173d0ab27b3de78b2f058
2023/01/17 13:06:01  info unpack layer: sha256:5ca731fc36c28789c5ddc3216563e8bfca2ab3ea10347e07554ebba1c953242e
INFO:    Creating SIF file...
INFO:    Build complete: lolcow.sif
$ apptainer exec lolcow.sif cowsay moo
 _____
< moo >
 -----
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

Accessing /HOME and /SCRATCH Within Container

A user home directory is mounted inside the container automatically. If you need access to the /SCRATCH storage for your computation, this must be mounted by the -B | --bind option.

Warning

The mounted folder has to exist inside the container or the container image has to be writable!

$ apptainer shell -B /scratch ubuntu.sif
Apptainer> ls /scratch
ddn  sys  temp  work

A comprehensive documentation can be found at the Apptainer Quick Start website.