In this system, it is possible to set up a container-based program execution environment using Apptainer (formerly Singularity). This section describes how to prepare the container image, customize the container, and build it.
 

Prerequisites

When using the work area, be sure to execute the newgrp command before executing.

1 2 3

$ groups   　　ocean G12345  # Displays the groups to which you belong. "ocean" and "hpci" are administrative groups. $ newgrp G12345

By default, Apptainer cache data is stored in the home directory. Since the home directory has a 100GB quota, if you expect the data to exceed this limit, please set the following environment variable to store the cache in the work directory instead.

1	$ export APPTAINER_CACHEDIR=/octfs/work/[group_name]/[user_name]/[directory_name]

To clean the cache data, run the following command:

1	$ apptainer cache clean

Preparing the container image

This section explains how to obtain container images. You can obtain images from the local registry within OCTOPUS or from public registries on the Internet. You can also upload your own container images to OCTOPUS.
 

download from the local registry

Download the Apptainer container image from the local registry and create a sandbox. As an example, to retrieve the container image named test registered in the local registry/master_image, navigate to the directory where you want to create the sandbox and execute the following command.
1 2 3

$ apptainer build -f --sandbox --fix-perms <sandbox name> oras://cntm:5000/<container image path>:<tag name> #The following is a sample of how to get the image "test". $ apptainer build -f --sandbox --fix-perms test oras://cntm:5000/master_image/test:1.0

If the container image is successfully downloaded, a sandbox (test in the above example) will be created in the current directory.
 

download from Docker Hub

Download the docker container image from Docker Hub and create a Apptainer sandbox.
For example, to get a RockyLinux container image from Docker Hub, navigate to the directory where you want to create the sandbox, and execute the following command.
1 2 3

$ apptainer build -f --sandbox --fix-perms <sandbox name> docker://<container image path>:<tag name> #The following is a sample of how to get a RockyLinux image. $ apptainer build -f --sandbox --fix-perms rocky9 docker://rockylinux:9

If the container image is successfully downloaded, a sandbox (rocky9 in the above example) will be created in the current directory.

 

Customizing and Building Container Images

This section describes how to customize and build container images. there are two ways to build container images with OCTOPUS: directly customize and build the sandbox, or write the customization in a def file and customize it at build time.
 

Direct customization of the sandbox

This section explains how to customize and build the sandbox directly. First, acquire the base container image you want to customize, and create a sandbox beforehand. Next, launch the sandbox as a container. As an example, to customize a sandbox called test, execute the following command.

1 2 3

$ apptainer run -f -w test The format is as follows $ apptainer run -f -w <sandbox name>

After the container is successfully started, you will see the Apptainer prompt. From the above prompt, you can add packages by dnf, pip, etc. (The commands used to manipulate the packages will vary depending on the OS distribution stored in the container.) After the customization of the container image is completed, stop the container with the exit command.
The next step is to build the container image and generate the sif file. As an example, to build a sandbox called test and create test.sif, execute the following command

1 2 3

$ apptainer build -f test.sif test The format of the command is as follows $ apptainer build -f <sif file> <sandbox name>

If the build is successful, a sif file will be created in the current directory.
 

How to describe the customization in the def file

This section explains how to write customization contents in a def file and customize it at build time. First, create a def file to be used for building.
As an example, if we want to customize the test registered in the local registry as the base container image, the def file will look like the following

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

Bootstrap: oras From: cntm:5000/master_image/test:1   %files            ./test.conf /opt/test.conf          ./test_start.sh /opt/test_start.sh   %post           dnf install -y net-tools         chmod 755 /opt/test_start.sh   %runscript           /opt/test_start.sh

def file summary *Please refer to the apptainer manual for details.
Bootstrap, From	Describe the type and location of the base image.
%file	Describe the file you want to copy from the host OS to the container.
%post	Describe the command for customization.
%runscript	Describe the process to be executed automatically when the container starts.

After the def file creation is complete, build the container image and generate the sif file. As an example, to build using a def file named test.def and create test.sif, execute the following command

1 2 3

$ apptainer build -f test.sif test.def The format of the command is as follows $ apptainer build -f <sif file> <def file>

If the build is successful, a sif file will be created in the current directory.
 

How to run a container

This section explains the essential knowledge required to run containers.
 

Execution Command

Container execution is performed by specifying the exec subcommand.

1 2 3

$ apptainer exec <sif file> <run command in the container> # The following is an example of running the hostname command in the rocky9.sif container image. $ apptainer exec rocky9.sif hostname

Note that the command you specify is an execution command in the container. If the command is pathless, the command explored with the PATH environment variable in the container is executed. Even if there is a path specified, the absolute path follows the file structure in the container.

Environment Variables

Environment variables defined outside of the container are basically carried over to the container.
However, environment variables that are explicitly defined on the container side, such as at build time, follow the container definition.
If you want to override environment variables defined in the container, you can pass them into the container either individually using the --env option or in bulk using the --env-file option.
• --env option to specify individually
1 2 3

$ apptainer exec --env <variable>=<value> <sif file> <run command in the container> # The following example executes ./a.out inside the rocky9.sif container with the environment variable MYVAR set to "My Value!". $ apptainer exec --env MYVAR="My Value!" rocky9.sif ./a.out

• --env-file option to specify in bulk
1 2 3

$ apptainer exec --env-file <env file> <sif file> <run command in the container> # The following example reads environment variables from the file "myenvfile" and executes ./a.out inside the rocky9.sif container. $ apptainer exec --env-file myenvfile rocky9.sif ./a.out

Mounting the Host OS

If you want to read/write the host OS's file system from within the container, you can bind mount a specific directory on the host OS. Even without specifying options, the following directories are mounted as standard and can be used in containers with the same path.
• Home directory：/octfs/home/[user_name]
• Temporary Region：/tmp

For example, the command to run a program (a.out) placed in the home directory of the host OS from within the container is as follows:


1 2 3

$ apptainer exec <sif file> <program> # The following example executes ./a.out, located in the host's home directory, inside the rocky9.sif container. $ apptainer exec rocky9.sif ./a.out

* In the above example, the current directory has been moved to home in the container.
 
To mount a specific directory from the host OS, use the --bind option. The format of the --bind option is as follows.
--bind : :
The path in the container and mode (ro/rw) are optional. If omitted, the path in the container is mounted in read/write with the same path as the host OS.
For example, the command to run a program (a.out) placed in a directory on the extension area is as follows:

1 2 3 4

$ cd /octfs/work/<group_name>/<user_name> $ apptainer exec --bind <host path> <sif file> <program> # The following example mounts the current directory (the result of `pwd`) into the container and executes ./a.out inside the rocky9.sif container. $ apptainer exec --bind `pwd` rocky9.sif ./a.out

* In the above example, the environment variable PWD outside the container is carried over to the container, and the current directory in the container is the directory in the extension area.

References

Apptainer User Guide