On November 30th, 2021, the Singularity project has officially moved into the Linux Foundation. As part of this move, and to differentiate from the other like-named projects and commercial products, the project is renamed to "Apptainer".
On our clusters, the Apptainer/Singularity images of main Linux distributions are prepared.
On our clusters, the Apptainer images of main Linux distributions are prepared.
```console
Barbora
├── CentOS
│├── 6
│ └── 7
├── Debian
│ └── latest
├── Fedora
│ └── latest
└── Ubuntu
└── latest
Barbora Karolina
├── CentOS ├── CentOS
| └── 7 |└── 7
├── Rocky ├── Rocky
| ├── 8 | ├── 8
│ └── 9 │ └── 9
├── Fedora ├── Fedora
│ └── latest │ └── latest
└── Ubuntu └── Ubuntu
└── latest └── latest
```
!!! info
Current information about available Apptainer/Singularity images can be obtained by the `ml av` command. The images are listed in the `OS` section.
Current information about available Apptainer images can be obtained by the `ml av` command. The images are listed in the `OS` section.
The bootstrap scripts, wrappers, features, etc. are located on [it4i-singularity GitLab page][a].
## IT4Innovations Apptainer/Singularity Wrappers
## IT4Innovations Apptainer Wrappers
For better user experience with Apptainer/Singularity containers, we prepared several wrappers:
For better user experience with Apptainer containers, we prepared several wrappers:
* image-exec
* image-mpi
...
...
@@ -33,8 +33,8 @@ For better user experience with Apptainer/Singularity containers, we prepared se
* image-shell
* image-update
Listed wrappers help you to use prepared Apptainer/Singularity images loaded as modules.
You can easily load a Apptainer/Singularity image like any other module on the cluster by the `ml OS/version` command.
Listed wrappers help you to use prepared Apptainer images loaded as modules.
You can easily load a Apptainer image like any other module on the cluster by the `ml OS/version` command.
After the module is loaded for the first time, the prepared image is copied into your home folder and is ready for use.
When you load the module next time, the version of the image is checked and an image update (if exists) is offered.
Then you can update your copy of the image by the `image-update` command.
...
...
@@ -42,51 +42,54 @@ Then you can update your copy of the image by the `image-update` command.
!!! warning
With an image update, all user changes to the image will be overridden.
The runscript inside the Apptainer/Singularity image can be run by the `image-run` command.
This command automatically mounts the `/scratch` and `/apps` storage and invokes the image as writable, so user changes can be made.
The runscript inside the Apptainer image can be run by the `image-run` command.
!!! note " CentOS/7 module only"
This command automatically mounts the `/scratch` and `/apps` storage and invokes the image as writable, so user changes can be made.
Very similar to `image-run` is the `image-exec` command.
The only difference is that `image-exec` runs a user-defined command instead of a runscript.
In this case, the command to be run is specified as a parameter.
Using the interactive shell inside the Apptainer/Singularity container is very useful for development.
Using the interactive shell inside the Apptainer container is very useful for development.
In this interactive shell, you can make any changes to the image you want,
but be aware that you can not use the `sudo` privileged commands directly on the cluster.
To simply invoke interactive shell, use the `image-shell` command.
Another useful feature of the Apptainer/Singularity is the direct support of OpenMPI.
Another useful feature of the Apptainer is the direct support of OpenMPI.
For proper MPI function, you have to install the same version of OpenMPI inside the image as you use on the cluster.
OpenMPI/3.1.4 is installed in prepared images.
OpenMPI/4.1.2 is installed in prepared images (CentOS 7, Rocky 8).
The MPI must be started outside the container.
The easiest way to start the MPI is to use the `image-mpi` command.
This command has the same parameters as `mpirun`, so there is no difference between running normal MPI application
and MPI application in a Apptainer/Singularity container.
and MPI application in a Apptainer container.
## Examples
In the examples, we will use prepared Apptainer/Singularity images.
In the examples, we will use prepared Apptainer images.
### Load Image
```console
$ml CentOS/6
Your image of CentOS/6 is at location: /home/login/.singularity/images/CentOS-6_20180220133305.img
Your image of CentOS/7 is at location: /home/username/.apptainer/images/CentOS-7_20230116143612.sif
```
!!! tip
After the module is loaded for the first time, the prepared image is copied into your home folder to the *.singularity/images* subfolder.
After the module is loaded for the first time, the prepared image is copied into your home folder to the *.apptainer/images* subfolder.
### Wrappers
**image-exec**
Executes the given command inside the Apptainer/Singularity image. The container is in this case started, then the command is executed and the container is stopped.
Executes the given command inside the Apptainer image. The container is in this case started, then the command is executed and the container is stopped.
```console
$ml CentOS/7
Your image of CentOS/7 is at location: /home/login/.singularity/images/CentOS-7_20180220104046.img
$image-exec cat /etc/centos-release
CentOS Linux release 7.3.1708 (Core)
$image-exec cat /etc/redhat-release
CentOS Linux release 7.9.2009 (Core)
```
**image-mpi**
...
...
@@ -95,55 +98,53 @@ MPI wrapper - see more in the [Examples MPI][1] section.
**image-run**
This command runs the runscript inside the Apptainer/Singularity image. Note, that the prepared images do not contain a runscript.
This command runs the runscript inside the Apptainer image. Note, that the prepared images do not contain a runscript.
**image-shell**
Invokes an interactive shell inside the Apptainer/Singularity image.
Invokes an interactive shell inside the Apptainer image.
```console
$ml CentOS/7
$image-shell
Singularity: Invoking an interactive shell within container...
Singularity CentOS-7_20180220104046.img:~>
Apptainer>
```
### Update Image
This command is for updating your local Apptainer/Singularity image copy.
This command is for updating your local Apptainer image copy.
The local copy is overridden in this case.
```console
$ml CentOS/6
New version of CentOS image was found. (New: CentOS-6_20180220092823.img Old: CentOS-6_20170220092823.img)
$ml CentOS/7
New version of CentOS image was found. (New: CentOS-7_20230116143612.sif Old: CentOS-7_20230115143612.sif)
For updating image use: image-update
Your image of CentOS/6 is at location: /home/login/.singularity/images/CentOS-6_20170220092823.img
Your image of CentOS/7 is at location: /home/username/.apptainer/images/CentOS-7_20230115143612.sif
$image-update
New version of CentOS image was found. (New: CentOS-6_20180220092823.img Old: CentOS-6_20170220092823.img)
New version of CentOS image was found. (New: CentOS-7_20230116143612.sif Old: CentOS-7_20230115143612.sif)
Do you want to update local copy? (WARNING all user modification will be deleted) [y/N]: y
If you want to use the Apptainer/Singularity wrappers with your own images, load the `Singularity-wrappers/master` module and set the environment variable `IMAGE_PATH_LOCAL=/path/to/container.img`.
If you want to use the Apptainer wrappers with your own images, load the `apptainer-wrappers/1.0` module and set the environment variable `IMAGE_PATH_LOCAL=/path/to/container.img`.
[Singularity][a] enables users to have full control of their environment. A non-privileged user can "swap out" the operating system on the host for one they control. So if the host system is running RHEL6 but your application runs in Ubuntu/RHEL7, you can create an Ubuntu/RHEL7 image, install your applications into that image, copy the image to another host, and run your application on that host in its native Ubuntu/RHEL7 environment.
Singularity also allows you to leverage the resources of whatever host you are on. This includes HPC interconnects, resource managers, file systems, GPUs and/or accelerators, etc. Singularity does this by enabling several key facets:
* Encapsulation of the environment
* Containers are image based
* No user contextual changes or root escalation allowed
* No root owned daemon processes
This documentation is for Singularity version 2.4 and newer.
[Apptainer][a] is a container platform. It allows you to create and run containers that package up pieces of software in a way that is portable and reproducible. You can build a container using Apptainer on your laptop, and then run it on many of the largest HPC clusters in the world, local university or company clusters, a single server, in the cloud, or on a workstation down the hall. Your container is a single file, and you don’t have to worry about how to install all the software you need on each different operating system.
## Using Docker Images
Singularity can import, bootstrap, and even run Docker images directly from [Docker Hub][b]. You can easily run an RHEL7 container like this:
Apptainer can import, bootstrap, and even run Docker images directly from [Docker Hub][b]. You can easily run an CentOS container like this:
In this case, the image is downloaded from Docker Hub, extracted to a temporary directory, and Singularity interactive shell is invoked. This procedure can take a lot of time, especially with large images.
In this case, the image is downloaded from Docker Hub, extracted to a temporary directory, and Apptainer interactive shell is invoked. This procedure can take a lot of time, especially with large images.
## Importing Docker Image
Singularity containers can be in three different formats:
Apptainer containers can be in three different formats:
* read-only **squashfs** (default) - best for production
* writable **ext3** (--writable option)
* writable **(ch)root directory** (--sandbox option) - best for development
Squashfs and (ch)root directory images can be built from Docker source directly on the cluster, no root privileges are needed. It is strongly recommended to create a native Singularity image to speed up the launch of the container.
Squashfs and (ch)root directory images can be built from Docker source directly on the cluster, no root privileges are needed. It is strongly recommended to create a native Apptainer image to speed up the launch of the container.
The interactive shell can be invoked by the `singularity shell` command. This is useful for development purposes. Use the `-w | --writable` option to make changes inside the container permanent.
The interactive shell can be invoked by the `apptainer shell` command. This is useful for development purposes. Use the `-w | --writable` option to make changes inside the container permanent.
```console
hra0031@login4:~$singularity shell -w ubuntu.img
Singularity: Invoking an interactive shell within container...
$apptainer shell ubuntu.sif
Singularity ubuntu.img:~>cat /etc/lsb-release
Apptainer>cat /etc/lsb-release
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=16.04
DISTRIB_CODENAME=xenial
DISTRIB_DESCRIPTION="Ubuntu 16.04.3 LTS"
DISTRIB_RELEASE=22.04
DISTRIB_CODENAME=jammy
DISTRIB_DESCRIPTION="Ubuntu 22.04.1 LTS"
```
A command can be run inside the container (without an interactive shell) by invoking the `singularity exec` command.
A command can be run inside the container (without an interactive shell) by invoking the `apptainer exec` command.
A singularity image can contain a runscript. This script is executed inside the container after the `singularity run` command is used. The runscript is mostly used to run an application for which the container is built. In the following example, it is the `fortune | cowsay` command:
An Apptainer image can contain a runscript. This script is executed inside the container after the `apptainer run` command is used. The runscript is mostly used to run an application for which the container is built. In the following example, it is the `fortune | cowsay` command:
