Environment

Abstract

Container introduces an additional layer of indirection which does not inherit its host environment transparently. User will need to explicilty export environment varibales into the container environment. Furthermore management of the container images themselfs, as well as bind-mounting host file-systems into the container during run-time is under responsability of the user.

Variables

Apptainer provides multiple methods to set environment variables in the container, details are described in the Apptainer User Guide ¹. A container introduces an additional layer of indirection which does not inherit automatically environment variables set in the command execution environment used to launch the container. Hence it is up to the user to specify environment variables which require to be set in a container. There are two possible ways to do this, either by using command-line options for the apptainer command or by exporting environment variables with a specific prefix.

APPTAINERENV_

Env. Variable	Description
APPTAINERENV_*	Environment variables prefixed with APPTAINERENV_ will be set in the container
APPTAINERENV_APPEND_PATH	Append (added to the end) a colon separated list of paths to the PATH variable in the container
APPTAINERENV_PREPEND_PATH	Prepended (added to the start) a colon separated list of paths to the PATH variable in the container

Apptainer reads environment variables prefixed with APPTAINERENV_ from the execution environment and exports these in the container. The generic prefix can be used to set any number of environment variables. Within the containerized environment the prefix is removed from the environment variable name. For example a variable specified with the name APPTAINERENV_LUSTRE_HOME will be called LUSTRE_HOME within the container.

# use the generic prefix to set an environment variable for the container
» export APPTAINERENV_LUSTRE_HOME=$LUSTRE_HOME

# run the container an read the ennvironment variables
» apptainer exec $APPTAINER_CONTAINERS/debian11.sif env | grep ^LUSTRE
LUSTRE_HOME=/lustre/hpc/vpenso

The PATH environment variable is a special case. Users have the option to overwrite the variable in the container using the generic prefix or to either append or prepend to the existing PATH.

Note that in particular when using virtual application environments the use if the generic prefix is very useful in order to export LD_LIBRARY_PATH to the container:

export APPTAINERENV_LD_LIBRARY_PATH=$LD_LIBRARY_PATH
export APPTAINERENV_PREPEND_PATH=$LUSTRE_HOME/bin

Command Options

Option	Description
--env NAME=VALUE[,NAME=VALUE,...]	Specify a comma separated list of environment variables as NAME=VALUE pairs
--env-file <file>	Provide a file that contains environment variables as NAME=VALUE pairs

The command-line options listed set environment variables in a container:

# Path to the container image...
container=$APPTAINER_CONTAINERS/debian.sif

# ...download the offical Debian container image
apptainer pull $container docker://debian:latest

# Set an environment variable LUSTRE_HOME...
apptainer exec --env LUSTRE_HOME=$LUSTRE_HOME $container env | grep ^LUSTRE
# ...check visibility of the variable during container execution

Users of an VAE can set the Slurm command line option --singulairty-args to to specify environment variables. (Note that this is supported with meta-commands in batch scripts as well.)

srun ... --singularity-args="--env-file job.env" ...

Bind Mounts

Option	Description
--bind=src[:dest]	Specify bind paths, where src and dest are paths outside and inside of the container respectively.

The container run-time allows to bind mount directories from the host system. The bind path and mounts section in the Apptainer User Guide ² describes this in detail. Paths like $HOME, $PWD, /tmp and /lustre are mounted by default. Users define additional mounts with the following option:

# download the official Debian 10 container
apptainer pull $APPTAINER_CONTAINERS/debian10.sif docker://debian:10

# bind-mount the CernVM-FS repositoires available on the cluster
apptainer exec --bind /cvmfs $APPTAINER_CONTAINERS/debian10.sif

This is particularly useful to access the CVMFS repositories available on the cluster.

Image Cache

Environment Variable	Description
APPTAINER_CACHEDIR	Cache folder for images from a container registry.
APPTAINER_TMPDIR	Temporary directory to build container file-systems.

By default the container build cache is located in $HOME/.apptainer. Details about the container build environment are available in the Apptainer User Guide ³. Pay attention to the storage consumed by the container cache, since the amount of available space is limited by a quota on your network home-directory.

# show storage capacity used by the cache
apptainercache list

# clean up everything
apptainer cache clean

The environment variable listed in the table on top are used to configure the paths to the container caches. Following example store all container artifacts on volatile storage in the /tmp directory by setting both variables:

# create a user specific directory in /tmp
tmp=$(mktemp -d /tmp/$USER-apptainer-XXXXXX)
export APPTAINER_TMPDIR=$tmp
export APPTAINER_CACHEDIR=$tmp

Footnotes

1. Apptainer User Guide - Environment and Metadata
   http://apptainer.org/docs/user/main/environment_and_metadata.html

2. Apptainer User Guide - Bind Paths and Mounts
   http://apptainer.org/docs/user/main/bind_paths_and_mounts.html

3. Apptainer User Guide - Build Environment
   http://apptainer.org/docs/user/main/build_env.html#cache-folders