Skip to content

Building Containers

In this section we will build a container for Rocky Linux 8. This is the same operating system as the HPC uses.

In the examples below if the prompt is shown as local$ then you will need to run the command on a terminal on your own local Linux machine. This is because the command will require root privileges. If the prompt contains hpc$ then you can run the command on the HPC.

Remember: To get help on “apptainer” commands type apptainer help and help for the build options with apptainer help build.

Building your own Containers

For this step we need to be on your own local Linux machine! This is what you will see if you try and build an image on the HPC.

hpc$ apptainer build rocky8.sif rocky8.def
FATAL: You must be the root user, however you can use --remote or --fakeroot to build from a Apptainer recipe file.

So for this section login to your own Linux machine or a virtual linux machine (using VirtualBox https://www.virtualbox.org or a Nectar virtual machine https://nectar.org.au).

Create a definition file called rocky8.def like this:

BootStrap: yum
OSVersion: 8
MirrorURL: https://dl.rockylinux.org/pub/rocky/%{OSVERSION}/BaseOS/x86_64/os/
Include: dnf

%labels
    Maintainer Mike Lake
    Version 1.0

%help
    This is a Rocky Linux 8 container for running fortune and cowsay.

%runscript
    echo "Running the main script from inside the Rocky Linux 8 container."
    fortune | cowsay

%setup
    # These are only required if running on the HPC.
    mkdir -p ${APPTAINER_ROOTFS}/opt
    mkdir -p ${APPTAINER_ROOTFS}/scratch
    mkdir -p ${APPTAINER_ROOTFS}/shared

%post
    echo "Installing packages into the Rocky Linux 8 container"
    dnf -y install epel-release
    dnf -y install fortune-mod cowsay

The sections you can use (e.g. %runscript) are described here: https://apptainer.org/docs/user/latest/quick_start.html#build-images-from-scratch

Now build your image. 

local$ sudo apptainer build rocky8.sif rocky8.def

This will have created a largish file (~ 200 MB) rocky8.sif.

Run the Containers Application

You can perform this step on the HPC. Use scp or your whatever client you use to copy files to the HPC to upload your container image.

To find out what this container was built for we ask for some help. All containers should show a basic help message.

hpc$ apptainer run-help rocky8.sif 

This is a Rocky Linux 8 container for running fortune and cowsay.

Now run the container’s main run script:

hpc$ apptainer run rocky8.sif
Hello from inside the container. 

< Happiness is a hard disk. >
 ---------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||

This output came from inside this container running on the HPC.

You can also check what the operating system is inside your container. All Rocky Linux releases have a file /etc/os-release containing release information. Show this file inside the container with:

hpc$ apptainer exec rocky8.sif cat /etc/os-release
NAME="Rocky Linux"
VERSION="8.7 (Green Obsidian)"

If you ran this from the login node you would get this:

hpc$ cat /etc/os-release
NAME="Rocky Linux"
VERSION="Rocky Linux 8.7 (Green Obsidian)"

Note: see later for how to run a container as a PBS job!

Creating Sandbox Containers

When you build containers, the output format can be one of multiple formats.

  • a “.sif” file: This is the default format and it is a compressed read-only image format.
  • a sandbox directory: This is a container within a directory structure, and it is a writable format.

A common workflow is to use the “sandbox” mode for development of the container, and then build the final default image when done, as the default format is read-only image so cannot be modified.

local$ sudo apptainer build --sandbox rocky8_devel rocky8.def

This will have created a directory rocky8_devel. You can create a sandbox without root privileges, but to ensure proper file permissions it is recommended to do so as root.

Note: If you have already created an image and wish to overwrite it, you can do so with the –force option. This option must follow the build command.
$ sudo apptainer build --force --sandbox rocky8_devel rocky8.def

Using the Apptainer “shell” command we can shell into this sandbox and modify it.

Using shell to Explore and Modify Containers

You can use the Apptainer “shell” command to explore your sif file or sandbox. Here we shell into our read-only sif container. We do not need to use sudo. We can use all the normal commands that we would use in Linux:

hpc$ apptainer shell rocky8.sif
Apptainer>
Apptainer> ls /usr/
bin  etc  games  include  lib  lib64  libexec  local  sbin  share  src  tmp
Apptainer>

Here we shell into our sandbox directory rocky8_devel. We do need to use sudo here. 

local$ sudo apptainer shell rocky8_devel
Apptainer>
In the above examples, we shell into our sif container or sandbox, but they are still read-only. A sandbox container is only writable if you “shell into it” with the –writable option. It’s usual to do this as root to ensure you have permission to access the files and directories that you want to modify.

local$ sudo apptainer shell --writable rocky8_devel
Apptainer>

In the above you will find that you are root and the container is writable.

Who am I Inside the Container?

Let’s shell into our container on the HPC.

hpc$ apptainer shell rocky8.sif
Apptainer>
Run the command whoami to see who we are:

Apptainer> whoami
mlake
Apptainer>

The user remains the same inside and outside of the container. If you enter a container without root privileges, you are unable to obtain root privileges within the container.

Now do this on your local machine where you built your container but invoke it using sudo:

local$ sudo apptainer shell rocky8.sif
Apptainer>

Now we are the root user inside the container. You can check :-) 

Apptainer> whoami
root
Apptainer>

Inspect Containers

Most importantly you can extract container metadata and the definition file that was used to build the container. Run these two commands to see.

hpc$ apptainer inspect rocky8.sif
Maintainer: Mike Lake
Version: 1.0
org.label-schema.build-date: Tuesday_31_January_2023_16:35:20_AEDT
org.label-schema.usage.apptainer.version: 1.1.4-2.el8
.....

Run this to view the definition file used to build this container:

hpc$ apptainer inspect --deffile rocky8.sif