Skip to content

Apptainer

A Docker-compatible container platform for HPC

Homepage Version(s): 1.1.6

Software containerization is a popular solution for environment-level reproducibility. Apptainer is a software containerization solution for HPC and cluster systems such as the FSU HPC. It is compatible with Docker and is capable of automatically converting Docker containers to Apptainer containers

Note

Apptainer was previously known as 'Singularity'. In November, 2021 it was rebranded to 'Apptainer'. For backward compatibility, you can still use the singularity command as a substitute for the apptainer command.

Basic Usage#

The apptainer command is available by default when you log in to the HPC cluster.

1
2
[USERNAME@h22-login-24 ~]$ apptainer --version
apptainer version 1.1.6-1.el8

The run command syntax is as follows:

1
$ apptainer [OPTIONS] run CONTAINERNAME

Full Apptainer documentation and example use are available at the official Apptainer User Guide.

A note about Docker#

Docker is NOT available on the HPC. We require all users needing to use Docker containers convert them to Apptainer containers. See below for instructions on how to convert/import Docker containers to Apptainer.

Running Docker containers in Apptainer#

Note

This is a summary of the documentation found at the official documentation site.

To run a Docker container in Apptainer on the HPC, execute the command, apptainer run docker://[REPO]/[IMAGE:TAGS]. For example, to run the lolcow image provided by Syslabs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
$ apptainer run docker://ghcr.io/apptainer/lolcow
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
Getting image source signatures
Copying blob 5ca731fc36c2 done  
Copying blob 16ec32c2132b done  
Copying config fd0daa4d89 done  
Writing manifest to image destination
Storing signatures
2024/01/05 14:09:33  info unpack layer: sha256:16ec32c2132b43494832a05f2b02f7a822479f8250c173d0ab27b3de78b2f058
2024/01/05 14:09:34  info unpack layer: sha256:5ca731fc36c28789c5ddc3216563e8bfca2ab3ea10347e07554ebba1c953242e
INFO:    Creating SIF file...
INFO:    underlay of /etc/localtime required more than 50 (77) bind mounts
 _____________________________
< Fri Jan 5 14:09:38 EST 2024 >
 -----------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

The first time you run this command, it will automatically download the Docker image and convert it into a .sif image file. The .sif file will be stored in your home directory in a hidden folder: ~/.apptainer.

Subsequent runs will use the cached image file, unless you specify otherwise:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
$ apptainer run docker://ghcr.io/apptainer/lolcow
INFO:    Using cached SIF image
INFO:    underlay of /etc/localtime required more than 50 (77) bind mounts
 ______________________________
< Tue May 23 13:18:59 EDT 2023 >
 ------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

To "bust" the cache, and pull the original image, add the --disable-cache option:

1
$ apptainer run --disable-cache docker://sylabsio/lolcow

Specifying a custom cache directory#

By default, Apptainer creates a hidden directory in your home directory for building/converting workflows:

1
2
$ ls ~/.apptainer
cache  docker  metadata  sypgp

Apptainer typically cleans up when it completes, but images are cached in that directory. If you use Apptainer and are running up against your quota, you may consider specifying a custom cache directory via the APPTAINER_CACHEDIR environment variable:

1
2
# In this example, we assume that the user has some storage space in the general access scratch volume
APPTAINER_CACHEDIR=/gpfs/research/scratch/USERNAME/

More information specifying a custom cache directory can be found at the official Apptainer documentation.

Building containers and comprehensive tutorial#

For a comprehensive tutorial on Apptainer, refer to the official quickstart guide.