The information provided in this article can be used on your workstation to build an Apptainer image. Some information here is also useful if you want to grab a ready-to-use Apptainer image from online resources for use on NAS systems.

Note: To use Apptainer on a NAS host machine, load an appropriate Apptainer module (apptainer/x86-toss4, apptainer/x86-toss5, apptainer/arm-toss5) depending on which architecture (x86_64 or aarch64) and operating system (toss4 or toss5) are on the host. See the second half of Enabling User-Defined Software Stack with Apptainer for more information.

Building an Apptainer Image

To build an Apptainer image, use the following:

host% apptainer build [local options ...] image_path build_spec

The image_path target specifies the output from the build process. The output can be one of the two formats:

• Default: The compressed Apptainer read-only image format (i.e., the default SIF format).
• Sandbox: This is a read-write container within a directory structure.

To build a compressed Apptainer read-only image, use the default format:

host% apptainer build ...

To build a read/write container within a directory structure, use the sandbox option:

host% apptainer build --sandbox ...

Note: It is common to use the sandbox mode to develop the container, as the image is writable. You can shell into it and install software and dependencies (some may require root privilege), until you are satisfied that your container will meet your needs. You can then build the container as a default Apptainer image for production use. The default format cannot be altered after it is created.

A build_spec target can be local or remote.

Acceptable formats for local targets include:

DEF file

Definition file, which contains a recipe for building a container. A sample DEF file is shown in Example 2 below. More samples can be found in Apptainer's GitHub.

buildkit

A build context directory, containing a Dockerfile to build.

directory

A directory structure containing a (ch)root filesystem.

image

A local image on your machine (such as *.sif or those with legacy Singularity formats).

For remote targets, use one of the following acceptable uniform resource identifiers (URI):

library://

An image library (no default).

docker://

A Docker registry (default is Docker Hub).

shub://

An Apptainer registry (default is Singularity Hub).

oras://

An OCI registry that holds SIF files using ORAS.

ipfs://

An IPFS cluster, using a HTTP gateway.

More details can be found here.

Examples for Building Apptainer Images

Example 1: Build an image from the GtHub Container Registry (GHCR) under Docker:

host% apptainer build lolcow.sif docker://ghcr.io/apptainer/lolcow

Example 2: Build an image from a definition (DEF) file by following these steps.

Note: This example is taken from Building containers from Apptainer definition files from the the Apptainer quickstart guide.

1. Create a sample definition file named lolcow.def with the following content.

   BootStrap: docker
   From: ubuntu:22.04
   
   %post
      apt-get -y update
      apt-get -y install cowsay lolcat
   
   %environment
      export LC_ALL=C
      export PATH=/usr/games:$PATH
   
   %runscript
      date | cowsay | lolcat

   Tip: For building Apptainer images with MPI libraries, see the examples in this Apptainer page. If you are building a container image from an existing base image located on a local system, use (for example):

   Bootstrap: localimage
   From: /path/to/your_local_image.sif
   
   % post
    ....

2. Build a SIF file from the DEF file using:

   host% apptainer build lolcow_from_def.sif lolcow.def

Example 3

Build a sandbox directory (named lolcow_from_sif) from the SIF file:

host% apptainer build --sandbox lolcow_from_sif  lolcow_from_def.sif

Example 4

Build a SIF image (lolcow_new.sif) from the sandbox directory:

host% apptainer build lolcow_new.sif lolcow_from_sif