Docker → Apptainer Migration¶

HPC clusters prohibit Docker (it requires root). The recommended container runtime for HPC is Apptainer (the successor to Singularity). pyCyto ships Apptainer definition files under containers/apptainer/.

Why Apptainer on HPC?¶

	Docker	Apptainer
Requires root	Yes	No
HPC cluster support	Rare	Standard
GPU passthrough	`--gpus all`	`--nv`
Image format	layered (OCI)	single `.sif` file
Runs as	root inside	same UID as caller

Building the GPU SIF¶

# From repo root, on a node with Apptainer installed
bash containers/apptainer/build.sh

# Or manually:
apptainer build containers/images/cyto-gpu.sif \
    containers/apptainer/cyto-gpu.def

containers/images/ is a symlink to the SIF storage directory. Set gpu_sif in scripts/benchmark/benchmark.user.toml after a successful build.

Running with Apptainer¶

# Execute a script inside the container (GPU enabled)
apptainer exec --nv containers/images/cyto-gpu.sif \
    pixi run -e gpu python scripts/benchmark/run_benchmark.py

# Interactive shell (useful for debugging)
apptainer shell --nv containers/images/cyto-gpu.sif

# Bind-mount a data directory
apptainer exec --nv \
    --bind /scratch/data:/data \
    containers/images/cyto-gpu.sif \
    pixi run -e gpu python my_script.py

Converting from Docker¶

If you have a working Docker image, convert it to SIF without Docker on the target machine:

# Option A: convert from local Docker daemon
docker build -f containers/Dockerfile -t cyto-gpu:latest .
apptainer build cyto-gpu.sif docker-daemon://cyto-gpu:latest

# Option B: convert from Docker Hub (no local build needed)
apptainer build cyto-gpu.sif docker://my-registry/cyto-gpu:latest

SLURM + Apptainer¶

In sbatch scripts, pass --nv to enable GPU passthrough:

#!/bin/bash
#SBATCH --partition=gpu_short
#SBATCH --gres=gpu:a100-pcie-40gb:1

apptainer exec --nv "$SIF_PATH" \
    pixi run -e gpu python scripts/benchmark/batch_segmentation.py "$@"

The SIF path is passed via an environment variable set in the benchmark orchestrator, or hardcoded in the sbatch template.

Definition File Structure¶

containers/apptainer/cyto-gpu.def follows the Apptainer definition format:

Bootstrap: docker
From: nvidia/cuda:11.8.0-cudnn8-runtime-ubuntu22.04

%post
    # Install pixi
    curl -fsSL https://pixi.sh/install.sh | bash
    # Install repo and environments
    git clone <repo> /opt/Cytotoxicity-Pipeline
    cd /opt/Cytotoxicity-Pipeline
    /root/.pixi/bin/pixi install -e gpu

%environment
    export PATH=/root/.pixi/bin:$PATH

%runscript
    cd /opt/Cytotoxicity-Pipeline
    exec pixi run -e gpu "$@"