---
title: "Apptainer Guide"
canonical: "https://kb.uconn.edu/space/SH/26231799924/Apptainer%20Guide"
format: markdown
---
Apptainer is the most widely used container system for HPC. It is a replacement (or next generation) for Singularity supported by the Linux Foundation.

Containers are a way to isolate your software and make it portable and reproducible. It is a valuable asset for reproducible science and, in addition,  Its use is especially recommended when

1. Users rely on “old” libraries (e.g., HDF4);
2. Users need to update their library constantly;
3. It also makes the user more independent of the cluster admins.

In this tutorial, we will show how to **build your own containers** on the cluster and **submit jobs using containers**.

## \uD83D\uDCD8 Instructions

The steps to build (or submit a job using) a container is available system wide.

Enter the following line a user’s .bashrc or local terminal before running apptainer:

```
export APPTAINER_TMPDIR=/gpfs/homefs1/netidhere
```

The above export line will tell Apptainer where to write tmp files.

Without the export line, apptainer will write to the local /tmp directory on a node and potentially fill up /tmp due to the low amount of available temp space on each node.

The path in the above export line can change depending on where a user would like to store their apptainer temp files before running apptainer.

There is also an apptainer module on HPC, but the apptainer module that is available is older and is subject to removal.

One can load the apptainer module with the following line:

```
module load apptainer
```

For the next step, we have two options: 1) to just use a prebuilt image, or  2) to use a `.def` file (called recipe) that will contain the instructions to build the container. When using the latter option, we can build our container on top of another prebuilt image.

> ℹ️ An **image **in the context of containers is a snapshot of an operating system (OS) along with a set of tools. For instance, an specific compiler. More information about the differences between containers and images can be found [here](https://phoenixnap.com/kb/docker-image-vs-container).

Building the container takes only one line of code, the structure (when building directly from a prebuilt image) is as follows

```
apptainer build [OPTION] <name-for-the-container> <library>://<prebuilt-image>
```

In order to know all the available “options”, one can run `apptainer build --help`. For the `<library>` part, usually we rely on [DockerHub](https://hub.docker.com/) (for more options see the [apptainer documentation](https://apptainer.org/docs/user/main/build_a_container.html#overview)). In general, we are interested in building a container image that is a single `.sif` file that can be transferred between computers. However, there is an interesting option called `--sandbox`, which creates an expandable container image. Sandboxes will be useful when trying to build a custom image. However, this type of container has two side effects. First, these containers take up more space. Secondly, they are not reproducible. 

### Building a container from a prebuilt image - `sf` and `R`

In the first example, we will build a container from a prebuilt image made available by the Rocker project [https://rocker-project.org/images/versioned/rstudio.html](https://rocker-project.org/images/versioned/rstudio.html). 

```
module load apptainer/1.1.3
apptainer build --force geospatial.sif docker://rocker/geospatial
```

There are many ways to interact with a built image. The most commonly used are `shell` and `exec`. The former is useful to check if “everything is in place”, while the latter is employed to execute commands within the container. Typically, we will use the `exec` command within `sbatch` scripts.

Below we are using `shell` to check whether `sf` and `terra` are among the installed packages.

```
apptainer shell geospatial.sif
Apptainer> R

R version 4.2.2 (2022-10-31) -- "Innocent and Trusting"
Copyright (C) 2022 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

  Natural language support but running in an English locale

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> all(c("sf", "terra") %in% installed.packages()[, 1])
[1] TRUE 
```

#### Submitting a job using the newly created container

We can execute our own scripts within the container as follows:

```
apptainer exec <container> <command> <script>
```

For instance, consider creating a script called `my-script.R` with the content below

```r
library(sf)
## reading a spatial dataset made available by `sf`
nc <- st_read(system.file("shape/nc.shp", package = "sf"))

## calculating the area of the small region in kilometers
min_area <-
    st_area(nc) |>
    min() |>
    units::set_units("km^2")

## saving it into a file called "my-example.dat"
write(x = min_area, file = "example.dat")
```

Now, let’s create a file to submit our job using `sbatch`. Create a file called `submit.sh` containing the code provided below.

```
#!/bin/bash
#SBATCH --partition=debug
#SBATCH --ntasks=1 # Job only requires 1 CPU core
#SBATCH --time=5   # Job should run for no more than 5 minutes
#SBATCH --error=job_%A.err
#SBATCH --output=job_%A.out

module load apptainer

apptainer exec \
	  geospatial.sif \
	  Rscript --vanilla my-script.R
```

This submission file will run on the `debug` partition. Errors and warnings will be saved on the `job_%A.err` file, while the output will be written into the `job_%A.out` file. So, to make it clear, we are running our script called `my-script.R` using the command `Rscript --vanilla` from within the container called `geospatial.sif`. Run `sbatch submit.sh` to submit the job.

## \uD83D\uDCCB Related articles



> Macro (contentbylabel)