Honfi001 at 06:54, 25 March 2026

2026-03-25T06:54:45Z

@@ Line 84: / Line 84: @@
 Once this completes, neofetch is installed — but only in the overlay. The original <code>ubuntu_24.04.sif</code> is still untouched.
-== Building a New Image from the Original + Overlay ==
+The takeaway tis that the an overlay enables a read-only image to be "modified" at runtime. This enables the use of applications that dowlooad data, e.g. databases at runtime.
 == Cleaning Up ==
@@ Line 125: / Line 107: @@
 |-
 | Install software || <code>apptainer exec --fakeroot --overlay $ov ubuntu_24.04.sif apt install -y neofetch</code>
 |-
 | Clean up overlay || <code>rm -rf $ov</code>
 |}

Honfi001: /* What is --fakeroot? */

2026-03-12T10:00:23Z

What is --fakeroot?

← Older revision		Revision as of 12:00, 12 March 2026
Line 42:		Line 42:
	So how do we install software into a container? This is where '''overlays''' and '''fakeroot''' come in.		So how do we install software into a container? This is where '''overlays''' and '''fakeroot''' come in.

	== What is ~~<code>--~~fakeroot~~</code>~~? ==		== What is fakeroot? ==

	On an HPC system you do not have root (administrator) privileges. But many operations inside a container — like installing packages with <code>apt</code> — expect to be run as root.		On an HPC system you do not have root (administrator) privileges. But many operations inside a container — like installing packages with <code>apt</code> — expect to be run as root.

Honfi001: Created page with "= Apptainer Overlays: Modifying Container Images = '''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. * Set you..."

2026-03-12T09:59:42Z

Created page with "= Apptainer Overlays: Modifying Container Images = '''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 you..."

New page

= Apptainer Overlays: Modifying Container Images =

'''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>

== Pulling the Base Image ==

Let's pull an Ubuntu 24.04 image from Docker Hub:

<syntaxhighlight lang="bash">
apptainer pull ./ubuntu_24.04.sif docker://ubuntu:24.04
</syntaxhighlight>

This will download and convert the image into a SIF file in your current directory.

== The Problem: SIF Images Are Read-Only ==

Now let's try to update the package list inside the container:

<syntaxhighlight lang="bash">
apptainer exec ubuntu_24.04.sif apt update
</syntaxhighlight>

This will fail. You will see errors about not being able to write to package lists and lock files. This is because SIF files are '''read-only''' by design — you cannot modify them directly.

So how do we install software into a container? This is where '''overlays''' and '''fakeroot''' come in.

== What is <code>--fakeroot</code>? ==

On an HPC system you do not have root (administrator) privileges. But many operations inside a container — like installing packages with <code>apt</code> — expect to be run as root.

The <code>--fakeroot</code> flag (or <code>-f</code>) tells Apptainer to make it ''look like'' you are running as root inside the container, even though you are not actually root on the host system. This is enough to trick package managers like <code>apt</code> into working.

== What is an Overlay? ==

An overlay is a writable layer that sits on top of a read-only SIF image. Think of it like putting a sheet of tracing paper over a printed page — you can write on the tracing paper without changing the original page underneath.

Any changes you make (installed packages, new files, config changes) are stored in the overlay, leaving the original SIF image untouched.

== Creating and Using an Overlay ==

Let's create a temporary directory to use as our overlay:

<syntaxhighlight lang="bash">
ov=$(mktemp -d)
</syntaxhighlight>

This creates a temporary directory somewhere under <code>/tmp</code> and stores the path in the variable <code>$ov</code>.

Now let's try that <code>apt update</code> again, this time with <code>--fakeroot</code> and <code>--overlay</code>:

<syntaxhighlight lang="bash">
apptainer exec --fakeroot --overlay $ov ubuntu_24.04.sif apt update
</syntaxhighlight>

This time it should work. Apptainer is running you as fake root, and any writes are going into the overlay directory instead of trying to modify the read-only SIF.

== Installing Software via the Overlay ==

Now let's install <code>neofetch</code> (a tool that displays system information) into the container through the overlay:

<syntaxhighlight lang="bash">
apptainer exec --fakeroot --overlay $ov ubuntu_24.04.sif apt install -y neofetch
</syntaxhighlight>

The <code>-y</code> flag tells <code>apt</code> to answer "yes" to all prompts automatically.

Once this completes, neofetch is installed — but only in the overlay. The original <code>ubuntu_24.04.sif</code> is still untouched.

== Building a New Image from the Original + Overlay ==

Right now your changes only exist in that temporary overlay directory. If you were to delete it or reboot, those changes would be gone. To make your modifications permanent, you can build a new SIF image that bakes in the overlay changes:

<syntaxhighlight lang="bash">
apptainer build --fakeroot ubuntu_neofetch.sif --overlay $ov ubuntu_24.04.sif
</syntaxhighlight>

This takes the original <code>ubuntu_24.04.sif</code>, applies everything in the overlay on top of it, and produces a brand new file: <code>ubuntu_neofetch.sif</code>.

== Testing the New Image ==

Let's verify that neofetch is available in our new image:

<syntaxhighlight lang="bash">
apptainer exec ubuntu_neofetch.sif neofetch
</syntaxhighlight>

You should see the familiar Ubuntu logo and system information output. Neofetch is now permanently part of this new image — no overlay or fakeroot needed to run it.

== Cleaning Up ==

Don't forget to remove the temporary overlay directory when you're done:

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

== Summary ==

{| class="wikitable"
|-
! Step !! Command
|-
| Pull base image || <code>apptainer pull ./ubuntu_24.04.sif docker://ubuntu:24.04</code>
|-
| Create overlay directory || <code>ov=$(mktemp -d)</code>
|-
| Update packages (with overlay + fakeroot) || <code>apptainer exec --fakeroot --overlay $ov ubuntu_24.04.sif apt update</code>
|-
| Install software || <code>apptainer exec --fakeroot --overlay $ov ubuntu_24.04.sif apt install -y neofetch</code>
|-
| Build new image from original + overlay || <code>apptainer build --fakeroot ubuntu_neofetch.sif --overlay $ov ubuntu_24.04.sif</code>
|-
| Test the new image || <code>apptainer exec ubuntu_neofetch.sif neofetch</code>
|-
| Clean up overlay || <code>rm -rf $ov</code>
|}

Tutorials/Apptainer-FakerootAndOverlays - Revision history

Honfi001 at 06:54, 25 March 2026

Honfi001: /* What is --fakeroot? */