Introduction
Apptainer ⤴ is, in fact, the evolution and rebranding of Singularity ⤴. In late 2021, the decision was made to reflect a broader mission and vision for the project. While Singularity originated as a container solution for HPC, it has since grown to serve more use cases beyond just HPC, including Edge and IoT (Internet of Things) Computing, Enterprise IT and Cloud, Data Mobility and Reproducibility. So now, Apptainer aims to serve a broader audience by addressing the needs of various computing environments and scenarios beyond just HPC.
Explore the journey from Singularity to Apptainer and uncover the expanded features and capabilities by visiting the official Apptainer website ⤴.
Useful Resources
- Apptainer Slack ⤴
- email lists: singularity@lbl.gov ⤴
- community help ⤴
- documentation ⤴
- Apptainer GitHub repo: https://github.com/apptainer/apptainer ⤴
- Singularity GitHub repo (archival): https://github.com/apptainer/singularity ⤴
- Frequently Asked Questions: ⤴
- What will the first version be?
- Sylabs still has a Singularity, how does Apptainer relate to that?
- What immediate changes will be implemented?
- What about backwards compatibility?
"Apptainer will provide singularity as a command line link and will maintain as much of the CLI and environment functionality as possible. From the user's perspective, very little, if anything, will change."
Apptainer User Guide
To get started with Apptainer, it’s highly recommended to follow the latest Apptainer User Guide ⤴. This comprehensive manual offers ordered and detailed instructions, ensuring users can easily navigate and utilize the features of Apptainer effectively and efficiently.
Apptainer as container technology
Containers, like Apptainer, address the challenge of installing and configuring custom software in the user space of Unix systems, HPC in particular, where regular user does not have root privileges.
Apptainer (previously Singularity) offers some features that make it distinct from other container technologies like Docker, such as:
- run complex applications on HPC clusters
- ability to run containers without root privileges
- seamless compatibility with specialized HPC configurations
- focus on security, reproducibility, and portability
- open-source project
Apptainer on a local machine
Follow the guide provided in section Quick Start in the official Apptainer Documenattion, which is intended for running Apptainer on a computer where you will install Apptainer yourself.
If you want to use the Apptainer on the HPC infrastructure, see next section.
Apptainer on the HPC clusters
Apptainer provides a streamlined solution for running containers in high-performance computing (HPC) clusters, offering compatibility, security, and efficiency. Regular users can easily deploy, manage, and execute applications encapsulated in custom containers, ensuring consistency and reproducibility across complex computational environments.
Load Apptainer module
Apptainer is usually preconfigured by HPC administrators, allowing regular users to activate and utilize it simply by loading the corresponding module. To check if the Apptainer module is available on an HPC system, users can typically use the command:
module avail apptainer
to list available modules and search for Apptainer in the output:
--------------------------- /software/el9/modulefiles --------------------------- apptainer/1.1.8 apptainer/1.2.2 apptainer/1.2.5 (D) Where: D: Default Module
Users should choose the specific version of the Apptainer module they wish to work with, and activate it by loading the module using the command:
module load apptainer/<version> # e.g., module load apptainer/1.2.5
Once the desired Apptainer module version is loaded, users can then directly execute apptainer commands and manage their containers within the HPC environment.
apptainer --version
apptainer version 1.2.5
Apptainer temporary files
In the context of jobs in HPC environments, controlling the cache location can be crucial to ensure that jobs do not run out of space or hit quotas during execution. By setting the cache directory paths, users can:
1. optimize performance by placing the cache on a fast filesystem
2. and manage storage by avoiding directories with space constraints (such as home).
The APPTAINER_CACHEDIR and SINGULARITY_CACHEDIR are environment variables that determine where Apptainer (formerly Singularity) caches its temporary files during operations like image builds or container pulls.
| variable | description |
|---|---|
SINGULARITY_CACHEDIR |
This environment variable was used in Singularity versions to specify the directory where Singularity should cache images and layers during operations. Setting this variable allows users to control the caching location, especially useful in HPC environments where home directories might have quota limits. |
APPTAINER_CACHEDIR |
Given the rebranding from Singularity to Apptainer, it’s logical to infer that this environment variable serves a similar purpose for Apptainer as SINGULARITY_CACHEDIR did for Singularity. |
HPC admins might set default values for these variables to optimize system-wide performance or to prevent users from filling up specific filesystems with cache data. These defaults can be set in global configuration files or through module environments. When an admin sets these, users on the system will typically inherit these values automatically unless they override them.
In practice, it’s always a good idea for users to check whether these variables are set by default on their HPC system and to be aware of how to set them if needed.
set CACHEDIR variable
Check the current value
To see what is currently set for these environment variables, you can use the echo command:
echo $APPTAINER_CACHEDIR
Individual users can override the default settings by specifying their own values for these environment variables in their session or job scripts. This can be useful if a user has a specific directory they want to use for caching or if they’re encountering space issues with the default cache location.
If you’ve set $APPTAINER_CACHEDIR to a custom location, that directory will be used for caching instead of the default ~/.apptainer. However, if $APPTAINER_CACHEDIR points directly to ~/.apptainer, then they are functionally the same.
Set the value in a current session
Before running any Apptainer or Singularity command, you can export the desired cache directory by setting the environment variable in your shell or within a job script. For example:
export APPTAINER_CACHEDIR=/path/to/custom/cache
Permanent Setting
If you find yourself frequently setting these variables, you can add the export command to your shell’s startup scripts (e.g., .bashrc or .bash_profile) to set them automatically whenever you start a new session.
Remember that setting these variables will direct Apptainer or Singularity to use the specified directory for caching. Make sure the path you provide has enough space, especially if you’re pulling large images or frequently building containers. It’s also wise to periodically clean up old cache files to free up space using the command apptainer cache clean.
If a user doesn’t manually set these variables and there’s no default set by the admin, the Apptainer will use its own default caching location, which is typically in the user’s home directory or a temporary directory. By default, without setting $APPTAINER_CACHEDIR, Apptainer might use a directory like ~/.apptainer (in the user’s home directory) for its cache, similar to how Singularity used ~/.singularity by default.
ls -lha ~
drwx------. 2 alex.badacz alex.badacz 2 Oct 31 20:26 .apptainer
Move .apptainer dir outside home location
You can relocate the .apptainer directory from your home to a location without storage limits (e.g., /project path on SCINet clusters), and then create a symbolic link in your home pointing to the new location, ensuring that the cache remains accessible from the home directory without additional modifications.
For example, at Atlas or Ceres (SCINet clusters), you can do:
cd ~
mkdir /project/<your_project_dir>/<account_name>
mv .apptainer /project/<your_project_dir>/<account_name>/
chmod -R g+s /project/<your_project_dir>/<account_name>/.apptainer
ln -s /project/<your_project_dir>/<account_name>/.apptainer .apptainer
In my case it looked like this:
cd ~
mkdir /project/isu_gif_vrsc/alex
mv .apptainer /project/isu_gif_vrsc/alex
chmod -R g+s /project/isu_gif_vrsc/alex/.apptainer
ln -s /project/isu_gif_vrsc/alex/.apptainer .apptainer
ls -lha ~ drwx------. 2 alex.badacz alex.badacz 2 Oct 31 20:28 .apptainer -> /project/isu_gif_vrsc/alex/.apptainer/
Apptainer Commands
Apptainer (formerly Singularity) provides a variety of commands to manage and interact with containers.
With the rebranding from Singularity to Apptainer, the command-line keyword changed from singularity to apptainer. However, the structure and many of the options and arguments for the commands remained consistent, allowing for a familiar experience for those who had previously used Singularity.
Apptainer commands follow the structure of:
apptainer [command] [options] [arguments]
where:
- [command] represents the action to perform,
- [options] are specific settings or modifiers, and
- [arguments] are inputs or targets for the command.
The apptainer help command gives an overview of Apptainer options and subcommands:
apptainer help Linux container platform optimized for High Performance Computing (HPC) and Enterprise Performance Computing (EPC) Usage: apptainer [global options...] Description: Apptainer containers provide an application virtualization layer enabling mobility of compute via both application and environment portability. With Apptainer one is capable of building a root file system that runs on any other Linux system where Apptainer is installed. Options: -d, --debug print debugging information (highest verbosity) -h, --help help for apptainer --nocolor print without color output (default False) -q, --quiet suppress normal output -s, --silent only print errors -v, --verbose print additional information Available Commands: build Build an Apptainer image cache Manage the local cache capability Manage Linux capabilities for users and groups exec Run a command within a container help Help about any command inspect Show metadata for an image instance Manage containers running as services key Manage OpenPGP keys oci Manage OCI containers plugin Manage apptainer plugins pull Pull an image from a URI push Upload image to the provided URI remote Manage apptainer remote endpoints run Run the user-defined default command within a container run-help Show the user-defined help for an image search Search a Container Library for images shell Run a shell within a container sif siftool is a program for Singularity Image Format (SIF) file manipulation sign Attach a cryptographic signature to an image test Run the user-defined tests within a container verify Verify cryptographic signatures attached to an image version Show the version for Apptainer Examples: apptainer help <command> [<subcommand>] apptainer help build apptainer help instance start For additional help or support, please visit https://www.apptainer.org/docs/
…about example commands and options fronm the official docs: Overview of the Apptainer Interface.
Dive into tutorials focused on specific tasks related to creating and managing containers; even if they were crafted for Singularity, you can seamlessly adapt them by simply replacing the singularity keyword with apptainer. The list of tutorials is provided below.