Containers

Table of contents

  1. Apptainer
    1. Getting an image
    2. Running a container
    3. Using Apptainer in a job
    4. Using GPUs
  2. Podman
    1. Running a container
    2. Where images are stored
  3. Building images

Apptainer and Podman are beta features.

A container packages a program together with everything it needs to run (libraries, other tools, even a different Linux distribution) into a single image. Containers are a lightweight form of virtualization: they let you run software that would be difficult to install on Ada directly, and to run exactly the same software environment on Ada, your laptop or another cluster. Many tools are already published as container images, e.g., on Docker Hub.

Ada supports two container tools:

  • Apptainer (recommended for most users) is designed for HPC. Each image is a single file you can keep in your home directory and use on any node, and it works well with GPUs and SLURM.
  • Podman is a drop-in replacement for Docker. Use it if you need Docker-compatible commands, e.g., to build images from a Dockerfile or to follow instructions written for Docker.

As with any computationally intensive work, run containers inside a SLURM job, not on the head node.

Apptainer

Apptainer (formerly Singularity) is available on all nodes.

Getting an image

apptainer pull downloads an image and converts it into a single .sif file. For example, to download the official Python image from Docker Hub into your storage directory:

cd /storage/username
apptainer pull docker://python:3.12

This creates python_3.12.sif.

Running a container

Task Command
Run a command inside the container apptainer exec python_3.12.sif python3 my_script.py
Open a shell inside the container apptainer shell python_3.12.sif
Run the image’s default command apptainer run python_3.12.sif

Your home directory, /storage and the current directory are available inside the container, so your scripts and data can be used as normal.

Using Apptainer in a job 

#!/usr/bin/env bash
#SBATCH --job-name=container_test
#SBATCH --partition=short
#SBATCH --time=01:00:00
#SBATCH --mem=4G

apptainer exec /storage/username/python_3.12.sif python3 my_script.py

Using GPUs

On a GPU node, add the --nv option to make the GPUs available inside the container, e.g., apptainer exec --nv my_image.sif python3 train.py.

Podman

Podman runs and builds containers using the same commands as Docker (the docker command is also available as an alias for podman). Podman runs “rootless”, meaning containers run with your own permissions.

Running a container

Start an interactive job, then use Podman as you would Docker. We recommend using full image names (including the registry, e.g., docker.io/):

[ada ~]$ srun --partition=short --time=01:00:00 --mem=4G --pty bash -i
[node002 ~]$ podman run --rm docker.io/library/python:3.12 python3 -c "print('Hello from a container')"

Common commands include podman pull, podman images, podman build (or buildah) and podman-compose. Some builds require additional setup; see Building images. Containers launched within a job are limited to that job’s CPU and memory.

Where images are stored

Podman stores images on the local disk of the node where you run it (in /local/username/containers), not in shared storage. An image downloaded or built on one node is not available on other nodes, so pull or build images within each job that needs them. To share an image across nodes, save it and convert it to an Apptainer image:

podman save -o my_image.tar localhost/my_image
apptainer build my_image.sif docker-archive://my_image.tar

For GPU workloads, we recommend Apptainer.

Building images

You can build your own images with Podman (podman build -t my_image . from a directory containing a Dockerfile) or Apptainer (apptainer build --fakeroot my_image.sif my_image.def from an Apptainer definition file). As noted above, build within a SLURM job.

Builds with steps that switch users or change file ownership, which includes most software installs with apt-get, dnf or yum, require additional configuration of your account. Email mlinderman@middlebury.edu to request it. Once it is set up, run podman system migrate once if you had already used Podman.

Alternatively, build the image on a computer where you have administrator access (e.g., with Docker on your laptop), push it to a registry such as Docker Hub, and pull it on Ada.