Skip to content

Playing with Apptainer

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.

If you don’t have a local Linux machine to play with then just follow along. Later you can install your own Linux distribution using a virtual machine created with something like “Virtual Box” (https://www.virtualbox.org).

In the section below we will be following a modified version of the tutorial at: https://github.com/NIH-HPC/Singularity-Tutorial.

Fortune and Cowsay

Firstly lets introduce the two programs that we will install into our container; fortune and cowsay. Neither of these programs are installed on the eResearch HPC. 

hpc$ fortune
  bash: fortune: command not found
hpc$

You can though install these programs on your local Linux machine if you have one.

Each time you run the fortune program it will present to you a useful fortune.

local$ fortune
The following two statements are usually both true:
  There's not enough documentation.
  There's too much documentation.
       -- Larry Wall in <199709020026.RAA08431@wall.org>
local$

The program cowsay is a bit different, it requires an input from stdin (the standard input). The input is usually piped into it from an echo command or from the output of another program (like fortune).

local$ echo 'Hi, I am an angus cow' | cowsay
 _______________________
< Hi, I am an angus cow >
 -----------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
local$

and here we pipe the output of the fortune program into cowsay:

local$ fortune | cowsay
 ________________________________________
/ Experience is what causes a person to  \
\ make new mistakes instead of old ones. /
 ----------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
local$

Now we understand what those programs do we can download and run a container that contains those programs, thus running those two programs on the HPC even though they are not installed there.

Download and Run a Container

The container that we will use is from the Singularity Hub Archive now at Datalad. This is a registry for scientific linux containers. Apptainer can reference any container there using the “shub://” protocol. We will be using the “lolcow” container created by David Godlove.

First download that container using the apptainer pull command:

hpc$ apptainer pull shub://GodloveD/lolcow
Progress |===================================| 100.0% 
hpc$

You will now have a file named lolcow_latest.sif.

Now use the apptainer command run to run the containers “predefined runscript command”: 

hpc$ apptainer run lolcow_latest.sif 
 ______________________________________
/ Q: How many Marxists does it take to \
| screw in a light bulb? A: None: The  |
| light bulb contains the seeds of its |
\ own revolution.                      /
 --------------------------------------
        \   ^__^
         \  (oo)\_______
            (__)\       )\/\
                ||----w |
                ||     ||
hpc$

Try this a few times to see different quotes from “cowsay”.

You can also use the apptainer run command which will download, build and run the container directly from the Singularity Hub like this: apptainer run shub://GodloveD/lolcow. You can run this on our HPC or your local Linux machine. However that might be needlessly pulling down the image each time, its better to download a container once and run it locally.

Remember that the above cow with it’s comments actually came from two programs; fortune and cowsay. The output of fortune is being piped into the cowsay program. We can just run the fortune command only using the exec option as in the command below. This “executes” a custom command.

hpc$ apptainer exec lolcow_latest.sif fortune
Bank error in your favor. Collect $200.
hpc$

What’s in a Container

We can also inspect this image to find out some details about it:

hpc$ apptainer inspect lolcow_latest.sif 

"org.label-schema.build-date": "Wednesday_3_July_2019_12:55:25_AEST",
"org.label-schema.build-size": "336MB",
"org.label-schema.schema-version": "1.0",
"org.label-schema.usage.singularity.deffile": "Singularity",
"org.label-schema.usage.singularity.deffile.bootstrap": "shub",
"org.label-schema.usage.singularity.deffile.from": "GodloveD/lolcow",
"org.label-schema.usage.singularity.version": "3.1.1-1.1.fc28"

Using inspect --deffile we can see the definition file (we will cover that next) that was used to create the image. Here we can see that the run command is actually the output of the fortune program piped into cowsay and then lolcat (lolcat just colorises the output). 

hpc$ apptainer inspect --deffile lolcow_latest.sif 
BootStrap: docker
From: ubuntu:16.04

%post
    apt-get -y update
    apt-get -y install fortune cowsay lolcat

%environment
    export LC_ALL=C
    export PATH=/usr/games:$PATH

%runscript
    fortune | cowsay | lolcat

That ends our quick tutorial on downloading and running container images. Typing apptainer help will give you an summary of all the commands you can use. Typing apptainer help <command> will give you more detailed information about running an individual command.

Now proceed to Building Containers to find out how to build your own container images.

Getting Help on Apptainer

Apptainer has a manual page:

hpc$ man apptainer

Also you can get general help on Apptainer commands with:

hpc$ apptainer help

To get help on a specific command use apptainer help commmand like this:

hpc$ apptainer help build