User Guide#

The User Guide covers a basic introduction to cotainr (this page) along with separate in-depth pages describing typical uses of cotainr. See the Getting Started guide for information about installing cotainr.

Why would I want to use cotainr?#

The two main reasons to use cotainr are:

It runs entirely in user space, i.e. you don’t need root/sudo priviledges (or fake them) to use cotainr.
It makes it a lot easier to build Singularity/Apptainer containers for certain HPC use cases.

In order to achieve this, the scope of cotainr is deliberately limited - focus is on making it easy to build reasonably performant containers for common HPC use cases. If you need a general purpose solution for building containers that achieve the absolute maximum performance, you should stick with Apptainer/Singularity instead of cotainr.

Dependencies#

Since cotainr is a tool, written in Python, for building Singularity/Apptainer containers, you need the following to be able to use cotainr:

A Linux OS (since Singularity/Apptainer only runs on Linux)
Python >=3.8
Singularity >=3.7.4 [1] or Apptainer >=1.0.0

Additionally, some features provided by cotainr may impose requirements on the base images you use when building containers, e.g. when including a conda environment the base container must have bash installed in it.

Command line interface#

The primary way to use cotainr is via its command line interface. The cotainr command provides a --help option that may be used to display all its options:

$ cotainr --help

Building a container#

Containers are built using the cotainr build subcommand, e.g.

$ cotainr build my_container.sif --base-image=docker://ubuntu:22.04

which would create the container my_container.sif based on the official Ubuntu 22.04 DockerHub image. The same could be achieved with:

$ cotainr build my_container.sif --system some-system

if the system some-system was defined to use the same docker image. These predefined systems can be listed with the info command, and will be defined by your system administrator to help you create containers.

Not specifying any further options to cotainr build than above, provides no more than what can be achieved with a singularity pull. In order to add software and files to the container, you need to use the options available with cotainr build. To list all options, run:

$ cotainr build --help

Also, take a look at the list of use cases for further inspiration to building containers using cotainr.

System information#

To make sure that everything is in your enviroment, you can run the cotainr info subcommand. This will provide you information about the system and also providing you with names of predefined systems.

$ cotainr info
Dependency report
-------------------------------------------------------------------------------
    - Running python 3.10.8 >= 3.8.0, OK
    - Found singularity 3.8.7 >= 3.7.4, OK

System info
-------------------------------------------------------------------------------
Available system configurations:
    - lumi-g
    - lumi-c

Python interface#

Power users may consider using the cotainr Python API as an alternative to the command line interface.

Use cases#

Typical use cases, that cotainr makes very easy to handle, include:

Creating a container based on a Conda environment

Examples#

Further examples of using cotainr are included with the source code, DeiC-HPC/cotainr:

Building a ROCm compatible PyTorch container for use on LUMI

Footnotes