Use Apptainer

Apptainer can be used as a container runtime environment on Charmed HPC for running containerized jobs. This guide provides examples of using Apptainer on Charmed HPC to accomplish different tasks.

New to Apptainer?

If you’re unfamiliar with using Apptainer in your jobs, see the Apptainer user quick start guide for a high-level introduction to using Apptainer on HPC clusters.

Prerequisites

To successfully use Apptainer on your Charmed HPC cluster, you will at least need:

Once you have verified that Apptainer is integrated with your Charmed HPC, refer to the sections below for the different ways that you can use Apptainer on Charmed HPC.

Create a container image

Use an image from a public container registry

Apptainer can pull pre-existing container images from public container registries.

For example, to pull a Valkey container image from Dockerhub and start a local Valkey service on your cluster, run:

apptainer pull valkey.sif docker://ubuntu/valkey:7.2.10-24.04_stable
apptainer overlay create --size 1024 valkey.img
apptainer instance run --overlay valkey.img valkey.sif valkey

Next, use apptainer exec to test your connection to the Valkey service:

apptainer exec instance://valkey valkey-cli ping

If the Valkey service is active, the output of apptainer exec will be similar to the following:

user@login:~$
apptainer exec instance://valkey valkey-cli ping 
PONG

Using images from other container registries

You can use apptainer help pull to view the full list of public container registries Apptainer can pull images from.

Build your own image

Before attempting to build your own container images

Check with your cluster administrator before attempting to build container images on your Charmed HPC cluster. Each site has different policies about whether you can build container images directly on your cluster, and some disallow building container images on specific cluster resources such as login nodes.

Apptainer can build container images using instructions from a container definition file.

For example, to build an Ubuntu 24.04 LTS-based container image with the gfortran compiler pre-installed, create the container definition file fortran-runtime.def:

fortran-runtime.def
bootstrap: docker
from: ubuntu:24.04

%post
    apt-get -y update
    apt-get -y install gfortran

%test
    gfortran --version
    exit 0

Then, use apptainer build to build your container image:

apptainer build fortran-runtime.sif fortran-runtime.def

Next, create a simple Fortran program the prints “Hello world!” in the file hello.f90:

hello.f90
PROGRAM hello_world
  IMPLICIT NONE
  PRINT *, "Hello world!"
END PROGRAM hello_world

Now use your container with apptainer exec to compile and run your Fortran program:

apptainer exec fortran-runtime.sif gfortran --output hello hello.f90
apptainer exec fortran-runtime.sif ./hello

The output of apptainer exec will be similar to the following:

user@login:~$
apptainer exec fortran-runtime.sif ./hello 
Hello world!

Provide your job’s runtime environment

Use the apptainer command

The apptainer command can be called directly in scripts to run job steps in a container instance.

For example, to run some Python code using a containerized Python 3.13 interpreter, create the job script job.batch. In this job script, you will call the apptainer command directly, and you will submit the job to the partition compute:

job.batch
#!/usr/bin/env bash
#SBATCH --partition compute
#SBATCH --output job.out

apptainer pull python-3.13.sif docker://ubuntu/python:3.13-25.04
apptainer --silent exec python-3.13.sif \
  python3 -c 'import sys; print(f"Hello from Python {sys.version}!")'

Now use sbatch to submit your job script to Slurm:

sbatch job.batch

Then, use cat to view the results of your job after it completes:

cat job.out

The output of cat job.out will be similar to the following:

user@login:~$
cat job.out 
Hello from Python 3.13.3 (main, Aug 14 2025, 11:53:40) [GCC 14.2.0]!

Use the --container flag with srun

Jobs submitted to Slurm with srun can be run inside a container instance using Apptainer.

For example, to submit a job to the partition compute that will use an Ubuntu 22.04 LTS container image as the runtime environment, run:

srun --partition compute --container docker://ubuntu:22.04 \
  cat /etc/os-release | grep ^VERSION

The output of srun will be similar to the following:

user@login:~$
srun --partition compute --container docker://ubuntu:22.04 \ >   cat /etc/os-release | grep ^VERSION 
INFO:    Converting OCI blobs to SIF format
INFO:    Starting build...
INFO:    Fetching OCI image...
INFO:    Extracting OCI image...
INFO:    Inserting Apptainer configuration...
INFO:    Creating SIF file...
VERSION_ID="22.04"
VERSION="22.04.5 LTS (Jammy Jellyfish)"
VERSION_CODENAME=jammy