Honfi001: Created page with "= Apptainer Sandbox: Modifying Containers Interactively = '''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 fast. *..."

2026-03-12T12:22:43Z

Created page with "= Apptainer Sandbox: Modifying Containers Interactively = '''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. *..."

New page

= Apptainer Sandbox: Modifying Containers Interactively =

'''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 Sandbox? ==

In the previous tutorial we used overlays to make changes on top of a read-only SIF image. Another approach is to convert the image into a '''sandbox''' — a regular directory on disk that contains the full filesystem of the container. Because it is just a directory, you can write to it directly.

This makes it easy to interactively install software, edit config files, and generally tinker with the container before converting it back into a portable SIF file.

== Pulling as a Sandbox ==

First, create a temporary directory and pull the Ubuntu 24.04 image directly as a sandbox:

<syntaxhighlight lang="bash">
sandbox=$(mktemp -d)
apptainer pull $sandbox/ubuntu --sandbox docker://ubuntu:24.04
</syntaxhighlight>

Instead of producing a single <code>.sif</code> file, this creates a directory at <code>$sandbox/ubuntu</code> that contains the entire container filesystem. You can <code>ls</code> it to see the familiar Linux directory structure:

<syntaxhighlight lang="bash">
ls $sandbox/ubuntu
</syntaxhighlight>

You should see directories like <code>bin</code>, <code>etc</code>, <code>usr</code>, <code>var</code>, and so on — just like a normal Linux root filesystem.

== Entering the Sandbox ==

Now let's open an interactive shell inside the sandbox:

<syntaxhighlight lang="bash">
apptainer shell --containall --writable --fakeroot $sandbox/ubuntu
</syntaxhighlight>

We are using three flags here, each doing something important:

{| class="wikitable"
|-
! Flag !! What it does
|-
| <code>--containall</code> (or <code>-C</code>) || Fully isolates the container from the host system. Your home directory, host environment variables, and host filesystems are '''not''' mounted into the container. This gives you a clean environment.
|-
| <code>--writable</code> (or <code>-w</code>) || Allows you to make changes to the container's filesystem. Without this flag, even a sandbox would be mounted read-only.
|-
| <code>--fakeroot</code> (or <code>-f</code>) || Makes it look like you are running as root inside the container. This is needed because package managers like <code>apt</code> expect root privileges to install software.
|}

Your prompt should change to <code>Apptainer></code>, indicating you are now inside the container.

== Installing Software ==

From inside the container, update the package lists and install <code>nano</code>, <code>cowsay</code> and <code>fortune-mod</code>:

<syntaxhighlight lang="bash">
Apptainer> apt-get update
Apptainer> apt-get install -y nano cowsay fortune-mod
</syntaxhighlight>

Once the installation finishes, clean up the apt cache to keep the image small:

<syntaxhighlight lang="bash">
Apptainer> apt-get clean
</syntaxhighlight>

== Fixing the PATH ==

In Ubuntu, <code>cowsay</code> and <code>fortune</code> are installed into <code>/usr/games/</code>, which is '''not''' in the default PATH for non-interactive shells. If we were to build a SIF from this sandbox right now, running <code>fortune</code> or <code>cowsay</code> would fail with a "command not found" error.

We need to add <code>/usr/games</code> to the container's PATH. Apptainer reads environment settings from files in <code>/.singularity.d/env/</code>. Run this command inside the container:

<syntaxhighlight lang="bash">
Apptainer> echo 'export PATH=/usr/games:${PATH}' >> /.singularity.d/env/90-environment.sh
</syntaxhighlight>

This appends a line to the environment script that ensures <code>/usr/games</code> is on the PATH every time the container runs.

== Editing the Runscript ==

The '''runscript''' is the command that gets executed when you use <code>apptainer run</code> on the container. It lives at <code>/.singularity.d/runscript</code>. Let's edit it so that our container does something fun by default.

Open the runscript with nano:

<syntaxhighlight lang="bash">
Apptainer> nano /.singularity.d/runscript
</syntaxhighlight>

You should see something like:

<syntaxhighlight lang="bash">
#!/bin/sh
OCI_ENTRYPOINT=''
# ...various lines...
exec "$@"
</syntaxhighlight>

Add <code>fortune | cowsay</code> on the line just '''above''' the final <code>exec "$@"</code>, so the end of the file looks like this:

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

Save and exit nano (<code>Ctrl+O</code>, <code>Enter</code>, <code>Ctrl+X</code>).

Now exit the container:

<syntaxhighlight lang="bash">
Apptainer> exit
</syntaxhighlight>

== Building the Final SIF Image ==

Convert the sandbox back into a portable SIF file:

<syntaxhighlight lang="bash">
apptainer build fortune.sif $sandbox/ubuntu
</syntaxhighlight>

This compresses the entire sandbox directory into a single <code>fortune.sif</code> file.

== Running It ==

Now for the moment of truth:

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

You should see a random fortune displayed inside a speech bubble from a friendly cow. Something like:

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

Every time you run it, you get a different fortune.

== Cleaning Up ==

Remove the temporary sandbox directory:

<syntaxhighlight lang="bash">
rm -rf $sandbox
</syntaxhighlight>

== Summary ==

{| class="wikitable"
|-
! Step !! Command
|-
| Create temp directory || <code>sandbox=$(mktemp -d)</code>
|-
| Pull as sandbox || <code>apptainer pull $sandbox/ubuntu --sandbox docker://ubuntu:24.04</code>
|-
| Enter sandbox || <code>apptainer shell --containall --writable --fakeroot $sandbox/ubuntu</code>
|-
| Install software || <code>apt-get update && apt-get install -y nano cowsay fortune-mod && apt-get clean</code>
|-
| Fix PATH || <code>echo 'export PATH=/usr/games:${PATH}' >> /.singularity.d/env/90-environment.sh</code>
|-
| Edit runscript || <code>nano /.singularity.d/runscript</code>
|-
| Exit container || <code>exit</code>
|-
| Build SIF from sandbox || <code>apptainer build fortune.sif $sandbox/ubuntu</code>
|-
| Run it || <code>apptainer run fortune.sif</code>
|-
| Clean up || <code>rm -rf $sandbox</code>
|}

Tutorials/Apptainer-FakerootAndSandbox - Revision history