Honfi001: Created page with "= Apptainer Definition Files: Building Containers from a Recipe = '''Important:''' Before you begin, make sure the following are in place: * You are running on a '''compute node''', not a login node. Request an interactive session first (e.g. via `srun` or your scheduler). * Your `.sif` image files should be stored on '''Lustre''' (e.g. in your scratch space), not in your home directory. SIF files can be large and will eat through your home quota..."

2026-03-12T12:32:44Z

Created page with "= Apptainer Definition Files: Building Containers from a Recipe = '''Important:''' Before you begin, make sure the following are in place: * You are running on a '''compute node''', not a login node. Request an interactive session first (e.g. via <code>srun</code> or your scheduler). * Your <code>.sif</code> image files should be stored on '''Lustre''' (e.g. in your scratch space), not in your home directory. SIF files can be large and will eat through your home quota..."

New page

= Apptainer Definition Files: Building Containers from a Recipe =

'''Important:''' Before you begin, make sure the following are in place:

* You are running on a '''compute node''', not a login node. Request an interactive session first (e.g. via <code>srun</code> or your scheduler).
* Your <code>.sif</code> image files should be stored on '''Lustre''' (e.g. in your scratch space), not in your home directory. SIF files can be large and will eat through your home quota fast.
* Set your Apptainer cache to Lustre as well. Add this to your session (or your <code>.bashrc</code>):

<syntaxhighlight lang="bash">
export APPTAINER_CACHEDIR=$myScratch/apptainer_cache
</syntaxhighlight>

== Getting Started ==

Load the required modules:

<syntaxhighlight lang="bash">
module reset
module load utilities Apptainer
</syntaxhighlight>

== What is a Definition File? ==

In the previous tutorials we modified containers by hand — either through overlays or by entering a sandbox and running commands interactively. That works, but it has a problem: if someone else (or future you) wants to know exactly what was changed, there is no record of the steps taken.

A '''definition file''' (sometimes called a "def file" or "recipe") solves this. It is a plain text file that describes, step by step, how to build a container from scratch. Think of it like a cooking recipe: it lists the base ingredients and every instruction needed to produce the final result. Anyone with the same definition file can reproduce the exact same container.

== The Definition File ==

Create a file called <code>cowsay.def</code> with the following contents:

<syntaxhighlight lang="bash">
Bootstrap: docker
From: ubuntu:24.04

%post
apt-get update
apt-get install -y cowsay fortune-mod
apt-get clean

%environment
export PATH=/usr/games:${PATH}

%runscript
fortune | cowsay
exec "$@"
</syntaxhighlight>

Let's walk through each section.

=== <code>Bootstrap</code> and <code>From</code> (the Header) ===

<syntaxhighlight lang="bash">
Bootstrap: docker
From: ubuntu:24.04
</syntaxhighlight>

The header tells Apptainer where to get the base image to start from. <code>Bootstrap: docker</code> means we are pulling from a Docker/OCI registry, and <code>From: ubuntu:24.04</code> specifies which image. This is equivalent to the <code>apptainer pull docker://ubuntu:24.04</code> command we used in the earlier tutorials.

=== <code>%post</code> ===

<syntaxhighlight lang="bash">
%post
apt-get update
apt-get install -y cowsay fortune-mod
apt-get clean
</syntaxhighlight>

The <code>%post</code> section contains commands that run '''inside the container at build time''', as root. This is where you install software, download data, compile code, or make any other modifications to the container's filesystem. It is the equivalent of what we did interactively inside the sandbox shell.

=== <code>%environment</code> ===

<syntaxhighlight lang="bash">
%environment
export PATH=/usr/games:${PATH}
</syntaxhighlight>

The <code>%environment</code> section defines environment variables that are set every time the container runs. Here we add <code>/usr/games</code> to the PATH so that <code>cowsay</code> and <code>fortune</code> can be found. This replaces the manual <code>echo</code> to <code>90-environment.sh</code> that we did in the sandbox tutorial.

=== <code>%runscript</code> ===

<syntaxhighlight lang="bash">
%runscript
fortune | cowsay
exec "$@"
</syntaxhighlight>

The <code>%runscript</code> section defines the default action when someone uses <code>apptainer run</code> on the container. This replaces the manual edit we made to the runscript file in the sandbox tutorial. The <code>exec "$@"</code> line at the end allows the container to accept additional arguments if needed.

== Building the Image ==

With the definition file in place, build the SIF image:

<syntaxhighlight lang="bash">
apptainer build cowsay.sif cowsay.def
</syntaxhighlight>

Apptainer will pull the base Ubuntu image, run the <code>%post</code> commands to install the software, set up the environment and runscript, and package everything into <code>cowsay.sif</code>.

== Running It ==

<syntaxhighlight lang="bash">
apptainer run cowsay.sif
</syntaxhighlight>

You should see a random fortune inside a cow speech bubble:

<syntaxhighlight lang="text">
________________________________________
/ You will be awarded some great honor. \
\ /
----------------------------------------
\ ^__^
\ (oo)\_______
(__)\ )\/\
||----w |
|| ||
</syntaxhighlight>

The same result as the sandbox tutorial — but this time, every step is documented in a single file that anyone can inspect and reproduce.

== Summary ==

{| class="wikitable"
|-
! Step !! Command
|-
| Create the definition file || Write <code>cowsay.def</code> (see above)
|-
| Build the image || <code>apptainer build cowsay.sif cowsay.def</code>
|-
| Run it || <code>apptainer run cowsay.sif</code>
|}

=== Definition File Sections at a Glance ===

{| class="wikitable"
|-
! Section !! Purpose
|-
| <code>Bootstrap</code> / <code>From</code> || Where to get the base image (the starting point)
|-
| <code>%post</code> || Commands to run inside the container at build time (install software, configure things)
|-
| <code>%environment</code> || Environment variables set every time the container runs
|-
| <code>%runscript</code> || The default command executed by <code>apptainer run</code>
|}

Tutorials/Apptainer-DefinitionFiles - Revision history