SingularityCE Documentation

SingularityCE is an open-source container platform designed for ease-of-use on shared systems and High Performance Computing (HPC) environments. Unlike many other container platforms, it prioritizes integration over isolation, allowing seamless access to GPUs, high-speed networks, and parallel filesystems.

Key features include:

• SIF (Singularity Image Format): An immutable single-file container image format that supports cryptographic signatures and encryption.
• Mobility: The SIF format makes containers easy to transport and share.
• Security Model: Users remain the same user inside the container as they are outside, preventing unauthorized privilege escalation on the host system by default.

To use the --oci execution mode in SingularityCE, your system must provide one of the following:

1. squashfs-tools / squashfs version 4.5 or higher (provides the sqfstar utility).
2. squashfs-tools-ng (provides the tar2sqfs utility).

Distribution-specific setup:

• Debian/Ubuntu: squashfs-tools-ng is included in the standard dependency list provided in the system dependencies guide.
• Fedora: squashfs-tools includes sqfstar by default.
• RHEL / Alma Linux / Rocky Linux: Install squashfs-tools-ng via the EPEL repository. If you previously used the dctrud/squashfs-tools-ng COPR, remove it first:

sudo dnf copr remove dctrud/squashfs-tools-ng
# After enabling EPEL:
sudo dnf install squashfs-tools-ng

The COPYING project uses a dual-license model (BSD-3-Clause AND MPL-2.0). To determine which license applies to your usage, you must check the comment at the start of each individual file.

In the event of a conflict between this documentation and the file-level comments, the comment at the start of the file takes precedence.

The Singularity e2e suite runs tests in parallel by default. Most tests should be written to be thread-safe by using dedicated temporary directories under testenv.TestDir for all file operations.

When to use Sequential (SEQ) tests: Some tests cannot run in parallel because they modify global state, such as:

• Changing the current working directory.
• Changing the OS umask.
• Modifying files in the user's or root's home directory (e.g., $HOME/.singularity/remote.yaml).

How to mark a test as sequential: Use testhelper.NoParallel(func(*testing.T)) to wrap a test function. This marks it to be run in the SEQ group rather than the PAR group.

// Marking a test to run sequentially
np := testhelper.NoParallel

return testhelper.Tests{
    "use exclusive": np(c.remoteUseExclusive),
}

SingularityCE uses multiple third-party dependencies managed via go.mod and go.sum.

• Full Builds/Packages: A complete build or package of SingularityCE includes all listed dependencies.
• Library Usage: If you import github.com/sylabs/singularity/v4 into your own Go project, you may only be subject to a subset of these dependencies depending on which parts of the package you use.

When performing a self bootstrap, you can refine the image composition using the following options:

1. From:: While optional for self bootstraps, you can explicitly specify the root using From: /.
2. Exclude:: Highly recommended to prevent unnecessary or sensitive data from being included in the image tarball. You can provide space-separated paths to exclude.

Example definition snippet to exclude Docker data and specific user/application directories:

Bootstrap: self
Exclude: /var/lib/docker /home/vanessa /opt/*

Depending on your role, use the following resources to get started with SingularityCE:

For Users

To learn how to run and build containers, refer to the User Guide.

For System Administrators

To learn how to configure SingularityCE and understand its architecture and security features, refer to the Administrator Guide.

Installation

• From Source: Follow the instructions in INSTALL.md.
• Other Methods: See the official installation guide.

Clone the repository using git. It is recommended to use --recurse-submodules to ensure all necessary submodules are included.

git clone --recurse-submodules https://github.com/sylabs/singularity.git
cd singularity

If you have already cloned the repository without submodules, run:

git submodule update --init

To build a specific version, check out the corresponding release tag (e.g., v4.5.0):

git checkout --recurse-submodules v4.5.0