Esimerkkejä

Tämä osio sisältää esimerkkejä konttien rakentamisesta ja ajamisesta Roihussa.

Esimerkki: Python-virtuaaliympäristö

Seuraavaksi annamme esimerkin kontista, jossa on järjestelmän Python sekä virtuaaliympäristö, johon on asennettu Python-paketteja Pipillä. Voimme määritellä build-määrityksen seuraavasti:

python-pip.def

Bootstrap: docker
From: docker.io/rockylinux/rockylinux:9.8

%post
    # Replace the failing commands with always succeeding dummies.
    cp /usr/bin/true /usr/sbin/useradd
    cp /usr/bin/true /usr/sbin/groupadd

    # Install Python with system package manager.
    dnf -y update
    dnf -y install python3.11 python3.11-pip
    dnf -y clean all

    # Create a Python virtual environment and install packages using pip.
    python3.11 -m venv /opt/venv
    export PATH=/opt/venv/bin:$PATH
    python3.11 -m pip install --no-cache-dir numpy

%environment
    export PATH=/opt/venv/bin:$PATH

Nyt voimme rakentaa konttikuvan seuraavasti:

apptainer build --fakeroot --bind="$TMPDIR:/tmp" python-pip.sif python-pip.def

Lopuksi voimme suorittaa komentoja kontin sisällä. Voimme esimerkiksi testata konttia listaamalla Pipillä asennetut Python-paketit:

apptainer exec python-pip.sif pip --no-cache list

Esimerkki: Paikallisen kuvan laajentaminen

Voimme myös laajentaa olemassa olevia SIF-kuvia. Tässä esimerkissä laajennamme python-pip.sif-konttikuvaa lisäämällä siihen toisen Python-kirjaston seuraavasti:

python-pip-2.def

Bootstrap: localimage
From: python-pip.sif

%post
    # The %environment section of the base image is not sourced during %post,
    # so activate the virtual environment explicitly to install into it.
    export PATH=/opt/venv/bin:$PATH

    python3.11 -m pip install --no-cache-dir pandas

Nyt rakennamme kontin tavalliseen tapaan:

apptainer build --fakeroot --bind="$TMPDIR:/tmp" python-pip-2.sif python-pip-2.def

Listataan Pipillä asennetut paketit nähdäksesi lisäämämme paketit:

apptainer exec python-pip-2.sif pip --no-cache list

Esimerkki: Roihu-CPU-peruskontti OSU-mikrobenchmarkeilla

Tämä kuva on rakennettu x86_64-arkkitehtuurille, joten rakenna ja aja se Roihu-CPU:ssa (roihu-cpu.csc.fi).

Build-määritystiedosto:

container.def

Bootstrap: docker
From: satama.csc.fi/r_installation_spack/core-cpu-gcc-15.2.0:v2026_03

%arguments
    NPROCS=10

%post
    # Activate module environment and load default modules.
    . /opt/activate.sh

    # Install tools
    dnf -y install wget file which
    dnf -y clean all

    # Build osu benchmarks
    cd /opt
    wget -q http://mvapich.cse.ohio-state.edu/download/mvapich/osu-micro-benchmarks-7.4.tar.gz
    tar xf osu-micro-benchmarks-7.4.tar.gz
    cd osu-micro-benchmarks-7.4
    ./configure --prefix=/opt/osu-micro-benchmarks CC=mpicc CXX=mpicxx CFLAGS=-O3
    make -j{{ NPROCS }}
    make install
    cd ..
    rm -rf osu-micro-benchmarks-7.4 osu-micro-benchmarks-7.4.tar.gz

%runscript
    . /opt/activate.sh
    exec "$@"

Kun rakennat kontteja, aseta Apptainerin välimuistihakemisto niin, ettei peruskuva täytä kotihakemistosi kiintiötä (korvaa <project> projektillasi):

export APPTAINER_CACHEDIR=/scratch/<project>/$USER/.apptainer
apptainer build --fakeroot --bind="$TMPDIR:/tmp" container.sif container.def

Nyt voit ajaa komentoja kontin sisällä ympäristö aktivoituna seuraavasti:

Slurm-ympäristömuuttujat vaaditaan, jotta MPI toimii!

Slurm-ympäristömuuttujien on välityttävä kontin ympäristöön, jotta MPI toimii. Älä siis käytä --cleanenv, --contain tai vastaavia valitsimia.

batch.sh

#!/bin/bash
#SBATCH --account=<project>
#SBATCH --partition=test
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=1
#SBATCH --mem=2G
#SBATCH --time=00:05:00

module purge
srun apptainer run container.sif /opt/osu-micro-benchmarks/libexec/osu-micro-benchmarks/mpi/pt2pt/osu_bibw
srun apptainer run container.sif /opt/osu-micro-benchmarks/libexec/osu-micro-benchmarks/mpi/pt2pt/osu_latency

Pisteestä pisteeseen -benchmarkit tarvitsevat kaksi eri solmuilla olevaa MPI-tehtävää, mikä sopii test-osioon. Pidempään ajoon kokonaisilla solmuilla käytä sen sijaan medium-osiota ja jätä --mem pois, koska se varaa kokonaiset solmut.

sbatch batch.sh

Esimerkki: Roihu-GPU-peruskontti NCCL-testeillä

Tämä kuva on rakennettu Arm-pohjaisille (aarch64) Nvidia Grace -prosessoreille, joten rakenna ja aja ne Roihu-GPU:ssa (roihu-gpu.csc.fi).

Build-määritystiedosto:

container.def

Bootstrap: docker
From: satama.csc.fi/r_installation_spack/core-gpu-gcc-14.3.0-cuda-12.9.1:v2026_03

%arguments
    NPROCS=10

%post
    # Activate module environment and load default modules.
    . /opt/activate.sh

    # Install tools
    dnf -y install wget file which
    dnf -y clean all

    # Install NCCL Tests
    module load nccl
    cd /opt
    wget https://github.com/NVIDIA/nccl-tests/archive/refs/tags/v2.18.3.tar.gz
    tar xf v2.18.3.tar.gz
    rm v2.18.3.tar.gz
    cd nccl-tests-2.18.3
    make -j{{ NPROCS }} CUDA_HOME=$CUDA_HOME NCCL_HOME=$NCCL_INSTROOT
    make -j{{ NPROCS }} CUDA_HOME=$CUDA_HOME NCCL_HOME=$NCCL_INSTROOT MPI=1 MPI_HOME=$OPENMPI_INSTROOT NAME_SUFFIX=_mpi

%runscript
    . /opt/activate.sh
    module load nccl
    exec "$@"

Kun rakennat kontteja, aseta Apptainerin välimuistihakemisto niin, ettei peruskuva täytä kotihakemistosi kiintiötä (korvaa <project> projektillasi):

export APPTAINER_CACHEDIR=/scratch/<project>/$USER/.apptainer
apptainer build --fakeroot --bind="$TMPDIR:/tmp" container.sif container.def

Huomaa, että GPU-peruskuvat ovat yli 10 GB:n kokoisia, mikä ylittää 15 GiB:n kotihakemistokiintiön, kun välimuisti ja tuloksena syntyvä kuva lasketaan yhteen.

Nyt voit ajaa komentoja kontin sisällä ympäristö aktivoituna seuraavasti. single-skripti ajaa tavallisen NCCL-testin yhden solmun neljällä GPU:lla, kun taas mpi-skripti ajaa MPI-tuetun buildin kahden solmun yli. Molemmat käyttävät gputest-osiota, joka sallii enintään kaksi solmua, joissa kummassakin on neljä GPU:ta. Huomaa, ettei kumpikaan skripti aseta --mem-valitsinta: GPU-osioissa CPU-muisti varataan automaattisesti varattujen GPU:iden määrän perusteella.

batch_single.sh

#!/bin/bash
#SBATCH --account=<project>
#SBATCH --partition=gputest
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=1
#SBATCH --cpus-per-task=72
#SBATCH --gres=gpu:gh200:4
#SBATCH --time=00:15:00

module purge
srun apptainer run --nv container.sif /opt/nccl-tests-2.18.3/build/all_reduce_perf -b 8 -e 128M -f 2 -g 4

sbatch batch_single.sh

batch_mpi.sh

#!/bin/bash
#SBATCH --account=<project>
#SBATCH --partition=gputest
#SBATCH --nodes=2
#SBATCH --ntasks-per-node=4
#SBATCH --cpus-per-task=72
#SBATCH --gres=gpu:gh200:4
#SBATCH --time=00:15:00

module purge
srun apptainer run --nv container.sif /opt/nccl-tests-2.18.3/build/all_reduce_perf_mpi -b 8 -e 128M -f 2 -g 1

sbatch batch_mpi.sh

Esimerkki: Make-ohjelman käyttäminen konttien rakentamiseen

Makefilet ovat erinomainen tapa organisoida konttien rakentamisen logiikka. Jos et tunne Makefilejen toimintaa, suosittelemme lukemaan erinomaisen Makefile Tutorial -oppaan.

Tässä on esimerkki Makefilen käyttämisestä kontin rakentamiseen määritystiedostosta nimeltä container.def SIF-tiedostoksi nimeltä container.sif.

container.def

Bootstrap: docker
From: docker.io/rockylinux/rockylinux:9.8

Makefile

TMPDIR ?= /tmp
PREFIX := .

CONTAINER_SIF := $(PREFIX)/container.sif
CONTAINER_DEF := container.def

.PHONY: all
all: $(CONTAINER_SIF)

$(CONTAINER_SIF): $(CONTAINER_DEF)
    apptainer build --fakeroot --bind=$(TMPDIR):/tmp $@ $<

.PHONY: clean
clean:
    rm -f $(CONTAINER_SIF)

Kutsutaan Makea kontin rakentamiseksi:

make

Voimme myös kutsua makea argumenteilla, kuten PREFIX, rakentaaksemme kontin toiseen hakemistoon:

make PREFIX=/projappl/<project>

Esimerkki: Kiihdytetty visualisointisovellus

Aloita rakentamalla visualisointi -peruskuva, joka sisältää VirtualGL:n, sen riippuvuudet ja apuskriptit. Voimme rakentaa kiihdytetyt visualisointisovellukset, kuten Blenderin, visualisoinnin peruskuvan päälle. Sovellus tulee suorittaa peruskonttiin asennetulla vglrun_wrapper-skriptillä.

Muut sovelluskontit

CSC:llä on konttien build-reseptejä useille sovelluksille singularity-recipes -repositoriossa. Tässä ovat reseptit, jotka voidaan rakentaa Apptainerilla fakerootia käyttäen Roihussa: