Apptainer

This article is a draft

This is not a complete article: This is a draft, a work in progress that is intended to be published into an article, which may or may not be ready for inclusion in the main wiki. It should not necessarily be considered factual or authoritative.

Notice

This page is draft work-in-progress. At the time of writing (August 2022) Apptainer version 1.1 is in release candidate status and the full release may well induce further updates to this page. (This page's current content is correct for Apptainer version 1.0.)

If Currently Using Singularity

We strongly recommend that you start using Apptainer instead of Singularity. SingularityCE (up to v3.9.5) was adopted by The Linux Foundation and renamed to Apptainer with these changes:

• added experimental support for DMTCP checkpointing,
  • NOTE: Support for such is not in Singularity.
• removed support for the --nvccli command line option,
• removed support for apptainer build --remote,
• removed support the SylabsCloud remote endpoint replacing it with a DefaultRemote endpoint with no defined server for library://,
  • NOTE: If the SylabsCloud remote is needed, the previous default can be restored.
• renamed all executable names, paths, etc. having singularity in their names to have apptainer in them,
  • e.g., instead of using the singularity command one uses the apptainer command
  • e.g., the ~/.singularity directory is now ~/.apptainer
• renamed all environment variables having SINGULARITY in their names to have APPTAINER in them,

Should you need to port scripts, etc. to Apptainer, know Apptainer version 1 is backwards compatible with Singularity --so such porting can be done incrementally.

Using Apptainer

In order to use Apptainer one must first already have a container image, e.g., a .sif file or a "sandbox" directory created previously. If you don't already have a container image, see the section on building an image below.

Loading an Apptainer Module

In order to use the default version of Apptainer available run:

$ module load apptainer

To see the available versions of Apptainer that can be loaded run:

$ module spider apptainer

Running Programs Within a Container

Text to come.

apptainer run-help

Text to come.

apptainer run

Text to come.

apptainer shell

Text to come.

apptainer exec

Text to come.

apptainer instance

Text to come.

Bind Mounts and Persistent Overlays

Text to come.

Bind Mounts

Text to come.

Persistent Overlays

Text to come.

Building an Apptainer Container/Image

Apptainer images can be created in the following formats:

• as an SIF file, or,
• as a "sandbox" directory.

SIF files can contain multiple sections where each section is normally a squashfs, i.e., read-only and compressed, filesystem although read-write filesystems and overlay images can also be added to the SIF file. That said, unless such additional sections are present, one need not be concerned about the sections contained within an SIF file, e.g., the Apptainer build command produces a read-only SIF file when building images.

A "sandbox" directory is a normal directory in the filesystem that starts out as empty and as Apptainer builds the image it adds the files, etc. needed in the image to that directory. The contents of a "sandbox" directory should only be accessed, updated, etc. through the use of Apptainer. One might need to use a "sandbox" directory in situations where one needs read-write access in order to be able to update the container image. (By default SIF files are read-only.)

If the container image will not need to be updated, one should create an SIF file image as disk performance with such is much faster, e.g.,

• an SIF file, which can be many gigabytes in size, is a single file which will result in excellent disk access performance and inode use on underlying filesystems,
• an SIF file, is (typically) read-only and compressed further improving disk access speeds, and,
• an SIF file that is read-only can be used with bind-mounted directories and/or overlay images that are not read-only should such be needed.

Building a Sandbox Directory

In order to build a "sandbox" directory instead of an SIF file instead of providing an SIF file name, instead provide --sandbox DIR_NAME or -s DIR_NAME where DIR_NAME is the name of the to-be-created-directory where you want your "sandbox" image. For example, if the apptainer build command to create an SIF file was:

$ apptainer build bb.sif docker://busybox

then change bb.sif to a directory name, e.g., bb.dir, and prefix such with --sandbox:

$ apptainer build --sandbox bb.dir docker://busybox

Differences between building a "sandbox" image and a (normal) SIF file are:

• the SIF file's image will be contained in a single file, compressed, and read-only,
• the "sandbox" image will be placed in a directory, uncompressed, may contain thousands of files (depending on what exactly is in the image), and will be able to be read-write.

Within an account, using a "sandbox" directory will consume significant amounts of both disk space and file count quotas, thus, if read-write access to the underlying image is not normally required, you are advised to use an SIF instead. Additionally, using an SIF file will have higher disk access speeds to content contained within the SIF file.

Building an SIF File

NOTE: This section only discusses some basics of creating a simple compressed, read-only SIF file container image. See the Apptainer documentation for more advanced aspects of building images.

Text to come.

Example Use Cases

Using GPUs Within an Apptainer Container

Text to come.

Using Conda Within an Apptainer Container

Text to come.

Running MPI Programs Inside an Apptainer Container

Text to come.

Using Spack Within an Apptainer Container

Text to come.

FAQ

Text to come.

Message Passing Interface