cotainr.container module#

cotainr - a user space Apptainer/Singularity container builder.

This module implements the interaction with the container runtime.

Classes#

SingularitySandbox: A Singularity container sandbox context manager.

API reference#

class cotainr.container.SingularitySandbox(*, base_image, log_settings=None)#

Bases: object

A Singularity container sandbox context manager.

This creates and manipulates a Singularity sandbox, i.e. a temporary directory representing the container. As a final step, the sandbox should be converted into a SIF container image file.

Parameters:

base_imagestr: Base image to use for the container which may be any valid Apptainer/Singularity <BUILD SPEC>.
log_settingsLogSettings, optional: The data used to setup the logging machinery (the default is None which implies that the logging machinery is not used).

Attributes:

base_imagestr: Base image to use for the container.
sandbox_diros.PathLike or None: The path to the temporary directory containing the sandbox if within a sandbox context, otherwise it is None.
log_dispatcherLogDispatcher or None.: The log dispatcher used to process stdout/stderr message from Singularity commands that run in sandbox, if the logging machinery is used.

Methods

`add_metadata`()	Add metadata to the container sandbox.
`add_to_env`(*, shell_script)	Add shell_script to the sourced environment in the container.
`build_image`(*, path)	Build a SIF image file from sandbox.
`run_command_in_container`(*, cmd[, ...])	Run a command in the container sandbox.

add_metadata()#

Add metadata to the container sandbox.

The following metadata is added to the container sandbox:

“cotainr.command”: The full command line used to build the container.
“cotainr.version”: The version of cotainr used to build the container.
“cotainr.url”: The cotainr project url.

The container metadata may be inspected by running singularity inspect on the built container image file.

Notes

The metadata entries are added to the .singularity.d/labels.json file.

add_to_env(*, shell_script)#

Add shell_script to the sourced environment in the container.

The content of shell_script is written as-is to the /environment file in the Singularity container which is sourced on execution of the container.

Parameters:

shell_scriptstr: The shell script to add to the sourced environment in the container.

build_image(*, path)#

Build a SIF image file from sandbox.

Takes the current content of the sandbox and builds a SIF container image from it. The container image is outputted to path.

Parameters:

pathos.PathLike: Path to the built container image.

run_command_in_container(*, cmd, custom_log_dispatcher=None)#

Run a command in the container sandbox.

Wraps singularity exec of the cmd in the container sandbox` allowing for running commands inside the container sandbox context, e.g. for installing software in the container sandbox.

Parameters:

cmdstr: The command to run in the container sandbox.
custom_log_dispatcherLogDispatcher, optional: The custom log dispatcher to use when running the command (the default is None which implies that the SingularitySandbox log dispatcher is used).

Returns:

processsubprocess.CompletedProcess: Information about the process that ran in the container sandbox.

Notes

We pass several flags to the singularity exec command to provide maximum compatibility with different HPC systems. In particular, we use:

–no-home as trying to mount the home folder on some systems (e.g. LUMI) causes problems. Thus, when running a command in the container, you cannot reference files in your home directory. Instead you must copy all files into the container sandbox and then reference the files relative to the container root.
–no-umask as some systems use a default umask (e.g. 0007 on LUMI) that prevents you from accessing any files added to the container as a regular user when you run the built container, e.g. such files are owned by root:root with 660 permissions for a 0007 umask. Thus, all files added to the container by running a command in the container will have file permissions 644 (Apptainer/Singularity forces the umask to 0022). If you need other file permissions, you must manually change them.