NEMO2/Containers/Apptainer - Revision history

M Janczyk at 12:51, 11 May 2026

2026-05-11T12:51:01Z

← Older revision		Revision as of 14:51, 11 May 2026
Line 6:		Line 6:
	* Runs as the invoking user — no root required and no privilege escalation		* Runs as the invoking user — no root required and no privilege escalation
	* Uses SIF (Singularity Image Format), a single portable file		* Uses SIF (Singularity Image Format), a single portable file
	* Can ~~convert~~ Docker images to ~~SIF~~ at ~~build~~ ~~time~~		* Can pull Docker/OCI images directly from registries without a local Docker installation
	* No native Slurm plugin — call <tt>apptainer exec/run</tt> inside your batch script		* No native Slurm plugin — call <tt>apptainer exec/run</tt> inside your batch script

	== Image sources ==		== Image sources ==

	All major OCI registries work out of the box via <tt>docker://</tt> URIs ~~— no Docker installation needed~~.		All major OCI registries work out of the box via <tt>docker://</tt> URIs.

	{\| class="wikitable"		{\| class="wikitable"
Line 34:		Line 34:

	SIF files are plain files — store them wherever you like.		SIF files are plain files — store them wherever you like.
	To avoid filling your home quota, keep images in a [[Workspaces\|workspace]] and use a symlink ~~so your scripts don't need to change~~:		To avoid filling your home quota, keep images in a [[Workspaces\|workspace]] and use a symlink:

	<pre>		<pre>
Line 40:		Line 40:
	ws_allocate apptainer 100		ws_allocate apptainer 100

	# ~~create an~~ images ~~directory in~~ the workspace ~~and symlink it from home~~		# symlink ~/images to the workspace
	ln -s $(ws_find apptainer) ~/images		ln -s $(ws_find apptainer) ~/images
	</pre>

	Pull images directly into the workspace:

	<pre>
	apptainer pull ~/images/ubuntu.sif docker://ubuntu:24.04
	apptainer pull ~/images/pytorch.sif docker://nvcr.io/nvidia/pytorch:24.01-py3
	</pre>		</pre>

Line 56:		Line 49:
	IMAGE=$HOME/images/pytorch.sif		IMAGE=$HOME/images/pytorch.sif
	</pre>		</pre>

			== Default mounts ==

			The following paths are '''automatically mounted''' into every container (configured via <tt>bind path</tt> in <tt>/etc/apptainer/apptainer.conf</tt>):

			{\| class="wikitable"
			\|-
			! Host path !! Notes
			\|-
			\| <tt>/home</tt> \|\| home directory of the invoking user, read-write
			\|-
			\| <tt>/work</tt> \|\| all workspace filesystems, read-write
			\|}

			The paths inside the container are '''identical''' to the paths on the host system.

			Note that <tt>ws_*</tt> tools (e.g. <tt>ws_find</tt>, <tt>ws_list</tt>) are '''not available inside the container'''.
			Determine your workspace path on the login node before running the container.

	== Basic commands ==		== Basic commands ==
Line 81:		Line 92:
	<pre>		<pre>
	# exec: run a specific command		# exec: run a specific command
	apptainer exec ubuntu.sif python3 script.py		apptainer exec ~/images/ubuntu.sif python3 script.py

	# run: execute the container's default runscript		# run: execute the container's default runscript
	apptainer run ubuntu.sif		apptainer run ~/images/ubuntu.sif

	# shell: interactive shell		# shell: interactive shell
	apptainer shell ubuntu.sif		apptainer shell ~/images/ubuntu.sif
	</pre>		</pre>

	=== ~~GPU~~ ~~access~~ ===		=== Additional mounts ===

		⚫	To mount directories beyond the defaults:
⚫	Pass the <tt>--nv</tt> flag to enable NVIDIA GPU passthrough:

	<pre>		<pre>
	apptainer exec --nv ~~pytorch~~.sif ~~python3 train.py~~		apptainer exec --bind /tmp/mydata:/data ~/images/ubuntu.sif bash
	</pre>		</pre>

	=== ~~Bind-mount~~ ~~paths~~ ===		== GPU access ==

		⚫	Pass the <tt>--nv</tt> flag to enable NVIDIA GPU passthrough:
	<tt>/home</tt> and <tt>/work</tt> are available inside the container by default (Apptainer automatically binds a set of paths; check <tt>apptainer config</tt> for the system defaults).

⚫	To mount ~~additional~~ directories ~~explicitly~~:

	<pre>		<pre>
	apptainer exec --~~bind~~ /~~tmp~~/~~mydata:/data ubuntu~~.sif ~~bash~~		apptainer exec --nv ~/images/pytorch.sif python3 train.py
	</pre>		</pre>

			Unlike Enroot/Pyxis, GPU passthrough is '''not''' automatic — <tt>--nv</tt> must be specified explicitly.
⚫	== ~~Using Apptainer in a~~ Slurm batch job ==

		⚫	== Slurm batch job ==

	~~Unlike Enroot/Pyxis there~~ is no Slurm plugin; ~~simply~~ call <tt>apptainer</tt> from your batch script:		There is no Slurm plugin; call <tt>apptainer</tt> directly from your batch script:

	CPU job:		CPU job:
Line 125:		Line 136:
	</pre>		</pre>

			GPU job:
	GPU job (use <tt>--nv</tt> to pass through the allocated GPUs):

	<pre lang="bash">		<pre lang="bash">
Line 141:		Line 152:
	== Building images ==		== Building images ==

	Building a new SIF image from a definition file requires root (or ~~a system that supports~~ fakeroot/user namespaces).		Building a new SIF image from a definition file requires root (or fakeroot/user namespaces).
	On NEMO you cannot build images directly on the compute nodes.		On NEMO you cannot build images directly on the compute nodes.

Line 149:		Line 160:
	# Run on NEMO as usual		# Run on NEMO as usual

	Store images in a workspace (symlinked to <tt>~/images/</tt> ~~as described above~~) — not in <tt>$TMPDIR</tt>, which is job-local and deleted after the job.		Store images in a workspace (symlinked to <tt>~/images/</tt>) — not in <tt>$TMPDIR</tt>, which is job-local and deleted after the job.

	== Tips ==		== Tips ==

M Janczyk at 12:15, 11 May 2026

2026-05-11T12:15:32Z

← Older revision		Revision as of 14:15, 11 May 2026
Line 10:		Line 10:

	== Image sources ==		== Image sources ==

			All major OCI registries work out of the box via <tt>docker://</tt> URIs — no Docker installation needed.

	{\| class="wikitable"		{\| class="wikitable"
	\|-		\|-
	! ~~Source~~ !! Example		! Registry !! URI prefix !! Example
			\|-
			\| Docker Hub \|\| <tt>docker://</tt> \|\| <tt>docker://ubuntu:24.04</tt>
			\|-
			\| NVIDIA NGC \|\| <tt>docker://nvcr.io/</tt> \|\| <tt>docker://nvcr.io/nvidia/pytorch:24.01-py3</tt>
	\|-		\|-
			\| quay.io \|\| <tt>docker://quay.io/</tt> \|\| <tt>docker://quay.io/rockylinux/rockylinux:9</tt>
	\| Apptainer Hub \|\| <tt>apptainer pull hello-world.sif library://lolcow</tt>
	\|-		\|-
	\| ~~Docker~~ ~~Hub~~ ~~(converted)~~ \|\| <tt>~~apptainer pull ubuntu~~.~~sif~~ docker://~~ubuntu:24~~.04</tt>		\| GitHub Container Registry \|\| <tt>docker://ghcr.io/</tt> \|\| <tt>docker://ghcr.io/containerd/alpine:latest</tt>
	\|-		\|-
	\| Local <tt>.sif</tt> file \|\| ~~copy~~ to ~~<tt>$HOME</tt>~~ or a workspace and use directly		\| Local <tt>.sif</tt> file \|\| — \|\| copy to a workspace and use directly
	\|}		\|}

			<tt>library://</tt> URIs (Sylabs Cloud Library) are '''not''' available by default — the default Apptainer installation has no Library API client configured.
			See [https://apptainer.org/docs/user/latest/endpoint.html#no-default-remote Apptainer docs] if you need to set up a library remote.

	== Image storage ==		== Image storage ==
Line 50:		Line 59:
	== Basic commands ==		== Basic commands ==

	=== Pull ~~/ build~~ an image ===		=== Pull an image ===

			Always pull images to a local SIF file first — using <tt>docker://</tt> URIs at runtime repeatedly can hit Docker Hub rate limits.

	<pre>		<pre>
	# from Docker Hub ~~→ produces ubuntu.sif in ~/images/~~		# from Docker Hub
	apptainer pull ~/images/ubuntu.sif docker://ubuntu:24.04		apptainer pull ~/images/ubuntu.sif docker://ubuntu:24.04

	# from NVIDIA NGC		# from NVIDIA NGC
	apptainer pull ~/images/pytorch.sif docker://nvcr.io/nvidia/pytorch:24.01-py3		apptainer pull ~/images/pytorch.sif docker://nvcr.io/nvidia/pytorch:24.01-py3

			# from quay.io
			apptainer pull ~/images/rockylinux.sif docker://quay.io/rockylinux/rockylinux:9

			# from GitHub Container Registry
			apptainer pull ~/images/alpine.sif docker://ghcr.io/containerd/alpine:latest
	</pre>		</pre>

Line 88:		Line 105:

	<pre>		<pre>
	apptainer exec --bind /~~work~~/~~classic/myWs~~:/data ubuntu.sif bash		apptainer exec --bind /tmp/mydata:/data ubuntu.sif bash
	</pre>		</pre>

M Janczyk: Created page with "'''Apptainer''' (formerly Singularity) is a container runtime designed for HPC systems. It is installed system-wide on NEMO and available without loading a module. == Key properties == * Runs as the invoking user — no root required and no privilege escalation * Uses SIF (Singularity Image Format), a single portable file * Can convert Docker images to SIF at build time * No native Slurm plugin — call `apptainer exec/run` inside your batch script == Image sou..."

2026-05-07T17:14:23Z

Created page with "'''Apptainer''' (formerly Singularity) is a container runtime designed for HPC systems. It is installed system-wide on NEMO and available without loading a module. == Key properties == * Runs as the invoking user — no root required and no privilege escalation * Uses SIF (Singularity Image Format), a single portable file * Can convert Docker images to SIF at build time * No native Slurm plugin — call <tt>apptainer exec/run</tt> inside your batch script == Image sou..."

New page

'''Apptainer''' (formerly Singularity) is a container runtime designed for HPC systems.
It is installed system-wide on NEMO and available without loading a module.

== Key properties ==

* Runs as the invoking user — no root required and no privilege escalation
* Uses SIF (Singularity Image Format), a single portable file
* Can convert Docker images to SIF at build time
* No native Slurm plugin — call <tt>apptainer exec/run</tt> inside your batch script

== Image sources ==

{| class="wikitable"
|-
! Source !! Example
|-
| Apptainer Hub || <tt>apptainer pull hello-world.sif library://lolcow</tt>
|-
| Docker Hub (converted) || <tt>apptainer pull ubuntu.sif docker://ubuntu:24.04</tt>
|-
| Local <tt>.sif</tt> file || copy to <tt>$HOME</tt> or a workspace and use directly
|}

== Image storage ==

SIF files are plain files — store them wherever you like.
To avoid filling your home quota, keep images in a [[Workspaces|workspace]] and use a symlink so your scripts don't need to change:

<pre>
# create a workspace (100 days)
ws_allocate apptainer 100

# create an images directory in the workspace and symlink it from home
ln -s $(ws_find apptainer) ~/images
</pre>

Pull images directly into the workspace:

<pre>
apptainer pull ~/images/ubuntu.sif docker://ubuntu:24.04
apptainer pull ~/images/pytorch.sif docker://nvcr.io/nvidia/pytorch:24.01-py3
</pre>

In batch scripts, reference images via the symlink:

<pre>
IMAGE=$HOME/images/pytorch.sif
</pre>

== Basic commands ==

=== Pull / build an image ===

<pre>
# from Docker Hub → produces ubuntu.sif in ~/images/
apptainer pull ~/images/ubuntu.sif docker://ubuntu:24.04

# from NVIDIA NGC
apptainer pull ~/images/pytorch.sif docker://nvcr.io/nvidia/pytorch:24.01-py3
</pre>

=== Run a command inside a container ===

<pre>
# exec: run a specific command
apptainer exec ubuntu.sif python3 script.py

# run: execute the container's default runscript
apptainer run ubuntu.sif

# shell: interactive shell
apptainer shell ubuntu.sif
</pre>

=== GPU access ===

Pass the <tt>--nv</tt> flag to enable NVIDIA GPU passthrough:

<pre>
apptainer exec --nv pytorch.sif python3 train.py
</pre>

=== Bind-mount paths ===

<tt>/home</tt> and <tt>/work</tt> are available inside the container by default (Apptainer automatically binds a set of paths; check <tt>apptainer config</tt> for the system defaults).

To mount additional directories explicitly:

<pre>
apptainer exec --bind /work/classic/myWs:/data ubuntu.sif bash
</pre>

== Using Apptainer in a Slurm batch job ==

Unlike Enroot/Pyxis there is no Slurm plugin; simply call <tt>apptainer</tt> from your batch script:

CPU job:

<pre lang="bash">
#!/bin/bash
#SBATCH -p cpu
#SBATCH --ntasks=1
#SBATCH --time=01:00:00

IMAGE=$HOME/images/ubuntu.sif

apptainer exec "$IMAGE" python3 /work/classic/myWs/train.py
</pre>

GPU job (use <tt>--nv</tt> to pass through the allocated GPUs):

<pre lang="bash">
#!/bin/bash
#SBATCH -p l40s
#SBATCH --gres=gpu:1
#SBATCH --ntasks=1
#SBATCH --time=01:00:00

IMAGE=$HOME/images/pytorch.sif

apptainer exec --nv "$IMAGE" python3 /work/classic/myWs/train.py
</pre>

== Building images ==

Building a new SIF image from a definition file requires root (or a system that supports fakeroot/user namespaces).
On NEMO you cannot build images directly on the compute nodes.

Recommended workflow:
# Build on a machine where you have root (local workstation, VM, GitHub Actions, …)
# Transfer the <tt>.sif</tt> file to NEMO (e.g. <tt>scp</tt>, <tt>rsync</tt>)
# Run on NEMO as usual

Store images in a workspace (symlinked to <tt>~/images/</tt> as described above) — not in <tt>$TMPDIR</tt>, which is job-local and deleted after the job.

== Tips ==

* Use <tt>apptainer exec --writable-tmpfs</tt> if the container tries to write to its own filesystem (without persisting changes).
* The <tt>--containall</tt> flag gives a fully isolated environment (no automatic bind-mounts); useful for reproducibility tests.
* To check what Apptainer version is installed: <tt>apptainer --version</tt>