SingularityCE

https://github.com/sylabs/singularity
Admin
SingularityCE is an open source container platform designed for simplicity, speed, and security on...
Tokens:40,436
Snippets:684
Trust Score:9.6
License:BSD-3-Clause
Update:1 month ago
Show doc for...
Tokens:
Raw
### Configure build options

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Example of setting a custom build directory and installation prefix.

```sh
./mconfig -b ./buildtree -p /usr/local
```

--------------------------------

### Build and install SingularityCE from release tarball

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Downloads the source tarball, builds the RPM, and installs it.

```sh
export VERSION=4.4.1 # this is the singularity version, change as you need

# Fetch the source
wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-ce-${VERSION}.tar.gz
# Build the rpm from the source tar.gz
rpmbuild -tb singularity-ce-${VERSION}.tar.gz
# Install SingularityCE using the resulting rpm
sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/singularity-ce-${VERSION}-1.el7.x86_64.rpm
# (Optionally) Remove the build tree and source to save space
rm -rf ~/rpmbuild singularity-ce-${VERSION}*.tar.gz
```

--------------------------------

### Build and Install SingularityCE

Source: https://github.com/sylabs/singularity/blob/main/AGENTS.md

Standard sequence for configuring, building, testing, and installing the project from source.

```sh
./mconfig -v                        # Configure
make -C builddir                    # Build
./builddir/singularity --version    # Smoke test
sudo make -C builddir install       # Install
make -C builddir check              # Lint
```

--------------------------------

### Build and install SingularityCE from repository

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Builds an RPM package from the cloned repository and installs it.

```sh
./mconfig
make -C builddir rpm
sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/singularity-ce-${VERSION}*.x86_64.rpm
```

--------------------------------

### Install golangci-lint

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Downloads and installs the latest version of the golangci-lint tool into the Go bin directory.

```sh
curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin
```

--------------------------------

### Install Go from binary archive

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Downloads and extracts the specified Go version to /usr/local. Ensure any existing Go installation is removed first.

```sh
export VERSION=1.26.7 OS=linux ARCH=amd64  # change this as you need

wget -O /tmp/go${VERSION}.${OS}-${ARCH}.tar.gz \
  https://dl.google.com/go/go${VERSION}.${OS}-${ARCH}.tar.gz
sudo tar -C /usr/local -xzf /tmp/go${VERSION}.${OS}-${ARCH}.tar.gz
```

--------------------------------

### Start SingularityCE VM

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Use this command to create and start a SingularityCE virtual machine using the provided Lima template.

```shell
limactl start ./singularity-ce.yml
```

--------------------------------

### Verify installation

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Checks the installed version of SingularityCE.

```sh
singularity --version
```

--------------------------------

### Install CLI Plugin

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Install the compiled plugin SIF file into the Singularity directory. Singularity will automatically load the plugin.

```bash
singularity plugin install ./examples/plugins/cli-plugin/cli-plugin.sif
```

--------------------------------

### Install squashfs-tools-ng on RHEL/Alma/Rocky

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Install the required squashfs-tools-ng package via dnf after enabling the EPEL repository.

```sh
sudo dnf install squashfs-tools-ng
```

--------------------------------

### Install additional headers on Ubuntu 24.04+

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Installs the libsubid-dev package required for newer Ubuntu releases.

```sh
sudo apt-get install -y libsubid-dev
```

--------------------------------

### Install Dependencies and Clone Singularity

Source: https://github.com/sylabs/singularity/blob/main/examples/arch/README.md

Installs necessary development tools and clones the Singularity repository. Ensure you are in the correct directory after cloning.

```bash
pacman -S -y git autoconf libtool automake gcc python make sudo vim \
 arch-install-scripts wget
git clone https://github.com/sylabs/singularity
cd singularity
git checkout -b development
git pull origin development
./autogen.sh
./configure --prefix=/usr/local
```

--------------------------------

### Singularity Instance Start with Authentication

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Starts a Singularity instance with authentication enabled, disabling cache and HTTPS. Use this for private repositories or when specific configurations are needed.

```bash
/usr/local/bin/singularity instance start --authfile ./my_local_authfile --disable-cache --no-https docker://localhost:41151/private/e2eprivrepo/my-alpine:latest actionAuthTesterInstance
```

--------------------------------

### Install build dependencies on RHEL/Alma/Rocky/Fedora

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Installs development tools and RPM dependencies for building SingularityCE on RHEL-based distributions.

```sh
# Install basic tools for compiling
sudo dnf groupinstall -y 'Development Tools'
# Install RPM packages for dependencies
sudo dnf --enablerepo=devel install -y \
    autoconf \
    automake \
    crun \
    cryptsetup \
    fuse \
    fuse3 \
    fuse3-devel \
    git \
    libseccomp-devel \
    libtool \
    shadow-utils-subid-devel \
    squashfs-tools \
    wget \
    zlib-devel
```

--------------------------------

### Get Help for a Specific App in Singularity

Source: https://github.com/sylabs/singularity/blob/main/examples/apps/README.md

Obtain help information for a particular application installed in a Singularity image. This is useful for understanding app-specific usage.

```console
$ singularity help --app fortune cowsay.simg
fortune is the best app
```

--------------------------------

### CLI Callbacks Test Setup

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Initializes a test for CLI callbacks, setting up a plugin directory, plugin name, and a SIF file. This snippet is part of a larger test function and defines the structure for test cases, including name, profile, command, arguments, and expected exit code.

```go
func (c ctx) testCLICallbacks(t *testing.T) {
	pluginDir := "./plugin/testdata/cli"
	pluginName := "github.com/sylabs/singularity/e2e-cli-plugin"

	// plugin sif file
	sifFile := filepath.Join(c.env.TestDir, "plugin.sif")
	defer os.Remove(sifFile)

	tests := []struct {
		name       string
		profile    e2e.Profile
		command    string
		args       []string
		expectExit int
	}{
		{
			name:       "Compile",
			profile:    e2e.UserProfile,
			command:    "plugin compile",

```

--------------------------------

### List Installed Plugins

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Query and display a list of all installed Singularity plugins, indicating their enabled status.

```bash
$ singularity plugin list
ENABLED  NAME
    yes  sylabs.io/cli-plugin
```

--------------------------------

### Build RPM with custom prefix

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Specifies a custom installation directory using the RPMPREFIX variable.

```sh
make -C builddir rpm RPMPREFIX=/opt/singularity-ce
```

--------------------------------

### Action Compatibility Tests with Varied Expectations

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Illustrates table-driven tests for action compatibility, including different arguments, exit codes, and output expectations. This example shows how to use `e2e.ExpectOutput` with `ContainMatch` and `UnwantedContainMatch` for verifying command output.

```go
func (c actionTests) actionCompat(t *testing.T) {
	e2e.EnsureImage(t, c.env)

	type test struct {
		name     string
		args     []string
		exitCode int
		expect   e2e.SingularityCmdResultOp
	}

	tests := []test{
		{
			name:     "containall",
			args:     []string{"--compat", c.env.ImagePath, "sh", "-c", "ls -lah $HOME"},
			exitCode: 0,
			expect:   e2e.ExpectOutput(e2e.ContainMatch, "total 0"),
		},
		{
			name:     "writable-tmpfs",
			args:     []string{"--compat", c.env.ImagePath, "sh", "-c", "touch /test"},
			exitCode: 0,
		},
		{
			name:     "no-init",
			args:     []string{"--compat", c.env.ImagePath, "sh", "-c", "ps"},
			exitCode: 0,
			expect:   e2e.ExpectOutput(e2e.UnwantedContainMatch, "sinit"),
		},
		{
			name:     "no-umask",
			args:     []string{"--compat", c.env.ImagePath, "sh", "-c", "umask"},
			exitCode: 0,
			expect:   e2e.ExpectOutput(e2e.ContainMatch, "0022"),
		},
	}

	oldUmask := syscall.Umask(0)
	defer syscall.Umask(oldUmask)

	for _, tt := range tests {
		c.env.RunSingularity(
			t,
			e2e.AsSubtest(tt.name),
			e2e.WithProfile(e2e.UserProfile),
			e2e.WithCommand("exec"),
			e2e.WithArgs(tt.args...),
			e2e.ExpectExit(
				t.exitCode,
				t.expect,
			),
		)
	}
}
```

--------------------------------

### Install dependencies on Debian/Ubuntu

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Updates package repositories and installs required development tools and libraries for Debian-based systems.

```sh
# Ensure repositories are up-to-date
sudo apt-get update
# Install debian packages for dependencies
sudo apt-get install -y \
    autoconf \
    automake \
    cryptsetup \
    fuse2fs \
    git \
    fuse3 \
    libfuse3-dev \
    libseccomp-dev \
    libtool \
    pkg-config \
    runc \
    squashfs-tools \
    squashfs-tools-ng \
    uidmap \
    wget \
    zlib1g-dev
```

--------------------------------

### Install conmon binary manually

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Download and install the conmon binary directly from GitHub releases for older distributions.

```sh
sudo curl -L -o /usr/local/bin/conmon https://github.com/containers/conmon/releases/download/v2.1.13/conmon.amd64
sudo chmod +x /usr/local/bin/conmon
```

--------------------------------

### Install conmon on Debian/Ubuntu

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Install the conmon package from official repositories for supported Debian and Ubuntu versions.

```sh
sudo apt-get install conmon
```

--------------------------------

### Uninstall Installed Plugin

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Remove a specific installed Singularity plugin from the system.

```bash
singularity plugin uninstall sylabs.io/cli-plugin
```

--------------------------------

### Compile and install on older Ubuntu versions

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Build process for Ubuntu 23.10 and older, requiring the --without-libsubid flag.

```sh
./mconfig --without-libsubid
make -C builddir
sudo make -C builddir install
```

--------------------------------

### List Installed Apps in Singularity Image

Source: https://github.com/sylabs/singularity/blob/main/examples/apps/README.md

Check which applications are installed within a Singularity image. This helps in understanding the available entrypoints.

```console
$ singularity apps cowsay.simg
cowsay
fortune
lolcat
```

--------------------------------

### Compile CLI Plugin

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Compile the example CLI plugin into a SIF file. The plugin code must be located within the Singularity source tree.

```bash
singularity plugin compile ./examples/plugins/cli-plugin
```

--------------------------------

### Install conmon on EL/Fedora

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Install the conmon package using the system package manager on EL or Fedora distributions.

```sh
sudo dnf install conmon
```

--------------------------------

### Inspect Plugin SIF File

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Examine the metadata of a plugin SIF file before installation to verify its details.

```bash
$ singularity plugin inspect examples/plugins/cli-plugin/cli-plugin.sif
Name: sylabs.io/cli-plugin
Description: This is a short test CLI plugin for Singularity
Author: Sylabs Team
Version: 0.1.0
```

--------------------------------

### Disable Installed Plugin

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Disable a specific installed Singularity plugin by its name.

```bash
singularity plugin disable sylabs.io/cli-plugin
```

--------------------------------

### E2ETests Function Example (REMOTE tests)

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Demonstrates how to use testhelper.NoParallel() to mark specific tests for sequential execution within a test group map.

```go
func E2ETests(env e2e.TestEnv) testhelper.Tests {
	c := ctx{
		env: env,
	}

	np := testhelper.NoParallel

	return testhelper.Tests{
		"add":            c.remoteAdd,
		"list":           c.remoteList,
		"default or not": c.remoteDefaultOrNot,
		"remove":         c.remoteRemove,
		"status":         c.remoteStatus,
		"test help":      c.remoteTestHelp,
		"use":            c.remoteUse,
		"use exclusive":  np(c.remoteUseExclusive),
	}
}
```

--------------------------------

### Example Test Names (PAR vs. SEQ)

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Illustrates how test names indicate whether a test runs in parallel (PAR) or sequentially (SEQ).

```plain
<...>\nTestE2E/PAR/BUILD/build_with_bind_mount\n<...>\nTestE2E/SEQ/DOCKER/cred_prio\n<...>
```

--------------------------------

### Get Singularity Version

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Determine the exact commit of the Singularity binary to ensure compatibility when building plugins.

```bash
$ singularity version
3.1.1-723.g7998470e7
```

--------------------------------

### Remove COPR repository for RHEL/Alma/Rocky

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Disable the legacy COPR repository for squashfs-tools-ng before installing from EPEL.

```sh
sudo dnf copr remove dctrud/squashfs-tools-ng
```

--------------------------------

### Run a Specific App in Singularity

Source: https://github.com/sylabs/singularity/blob/main/examples/apps/README.md

Execute a specific application installed within a Singularity image. This command allows direct interaction with individual SCIF apps.

```console
$ singularity run --app fortune cowsay.simg
When I reflect upon the number of disagreeable people who I know who have gone
to a better world, I am moved to lead a different life.
    -- Mark Twain, "Pudd'nhead Wilson's Calendar"
```

--------------------------------

### Singularity Instance Stop

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Stops a running Singularity instance. This command is used to terminate a previously started instance.

```bash
/usr/local/bin/singularity instance stop actionAuthTesterInstance
```

--------------------------------

### Create Test Source File

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Create the main source file for your test group.

```sh
touch e2e/env/env.go
```

--------------------------------

### Enter SingularityCE VM

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Access the SingularityCE virtual machine interactively to run commands.

```shell
limactl shell singularity-ce
```

--------------------------------

### Build Container Image from Specification File

Source: https://github.com/sylabs/singularity/blob/main/examples/self/README.md

This command sequence creates a container image of a specified size and then performs a bootstrap using a Singularity definition file.

```sh
singularity create --size 8000 container.img
sudo singularity bootstrap container.img Singularity
```

--------------------------------

### Run Go Tests

Source: https://github.com/sylabs/singularity/blob/main/AGENTS.md

Commands for executing unit and integration tests using the project's wrapper script.

```sh
# After configure and build steps in Quick Start

# Run all unit tests
scripts/go-test -v ./...

# Run single `TestPrefix` test from pkg/sylog
scripts/go-test -v ./pkg/sylog -run TestPrefix
```

--------------------------------

### Create and Bootstrap Arch Linux Image

Source: https://github.com/sylabs/singularity/blob/main/examples/arch/README.md

Creates a Singularity image file and then bootstraps it using the Arch Linux distribution. This command requires root privileges for the bootstrap process.

```bash
cd /tmp
singularity create arch.img
sudo singularity bootstrap arch.img Singularity
```

--------------------------------

### Clone the SingularityCE repository

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Initializes the repository with submodules in a chosen directory.

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

--------------------------------

### Complete env.go Test File

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

This is the complete `e2e/env/env.go` file, including package declaration, imports, context struct, test method, and the `E2ETests` function.

```go
package env 

import (
    "testing"

    "github.com/sylabs/singularity/e2e/internal/e2e"
    "github.com/sylabs/singularity/e2e/internal/testhelper"
)

type ctx struct {
    env e2e.TestEnv
}

func (c ctx) echoEnv(t *testing.T) {
    e2e.EnsureImage(t, c.env)

    env := []string{`FOO=BAR`}
    c.env.RunSingularity(
        t,
        e2e.WithProfile(e2e.UserProfile),
        e2e.WithCommand("exec"),
        e2e.WithEnv(env),
        e2e.WithArgs("/bin/sh", "-c" "echo $FOO"),
        e2e.ExpectExit(
            0,
            e2e.ExpectOutput(e2e.ExactMatch, "BAR"),
        ),
    )
}

func E2ETests(env e2e.TestEnv) testhelper.Tests {
    c := ctx{
        env: env,
    }

    return testhelper.Tests{
        "environment echo": c.echoEnv,
    }
}
```

--------------------------------

### Checkout a specific release tag

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Switches the repository to a specific version tag for building.

```sh
git checkout --recurse-submodules v4.5.1
```

--------------------------------

### Basic Self Bootstrap Configuration

Source: https://github.com/sylabs/singularity/blob/main/examples/self/README.md

Use 'Bootstrap: self' to indicate that the container should be built from the current operating system. No 'From' directive is needed as it defaults to the root.

```text
Bootstrap: self
```

--------------------------------

### Configure golangci-lint PATH

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Appends the Go GOPATH bin directory to the user's shell configuration file.

```sh
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Configure Go PATH

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Appends the Go binary directory to the user's shell configuration file.

```sh
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc
```

--------------------------------

### Create Test Helper Source File

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Optionally, create a separate source file for helper functions specific to your test group.

```sh
touch e2e/env/env_utils.go
```

--------------------------------

### Run Help Tests with Verbose and Filter Flags

Source: https://github.com/sylabs/singularity/blob/main/e2e/help/README.md

Modify the Makefile to include verbose and filter flags for `go test` to run specific help content tests.

```sh
SINGULARITY_E2E=1 make -C builddir e2e-test
```

--------------------------------

### Build Singularity SCIF Image

Source: https://github.com/sylabs/singularity/blob/main/examples/apps/README.md

Use this command to build a Singularity image with SCIF capabilities. Ensure you have the Singularity build environment set up.

```sh
sudo singularity build cowsay.simg Singularity.cowsay 
```

--------------------------------

### Implement Environment Variable Echo Test

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Write a test method that uses `c.env.RunSingularity` to execute a command with environment variables and verify the output.

```go
func (c ctx) echoEnv(t *testing.T) {
    e2e.EnsureImage(t, c.env)

    env := []string{`FOO=BAR`}
    c.env.RunSingularity(
        t,
        e2e.WithProfile(e2e.UserProfile),
        e2e.WithCommand("exec"),
        e2e.WithEnv(env),
        e2e.WithArgs("/bin/sh", "-c" "echo $FOO"),
        e2e.ExpectExit(
            0,
            e2e.ExpectOutput(e2e.ExactMatch, "BAR"),
        ),
    )
}
```

--------------------------------

### Run Specific E2E Test Path

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Use the `make -C builddir e2e-test -run` command with a specific test path to execute a single E2E test.

```console
make -C builddir e2e-test -run /my/specific/test/name/here
```

--------------------------------

### Build Singularity SIF Image

Source: https://github.com/sylabs/singularity/blob/main/examples/build-singularity/README.md

Use this command to build a Singularity Image Format (SIF) file for the Singularity container.

```shell
sudo singularity build build-singularity.sif build-singularity.def
```

--------------------------------

### Create and Push Release Branch

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Create a new release branch from main and push it to the remote repository.

```bash
git checkout upstream/main -b release-3.12
git push upstream release-3.12
```

--------------------------------

### Iterate Over Profiles for Singularity Commands

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Use a for-loop to iterate over a slice of profiles, running the same Singularity command with different profile configurations. This is useful for testing command behavior across various user environments.

```go
func (c actionTests) actionTmpSandboxFlag(t *testing.T) {
	e2e.EnsureImage(t, c.env)

	profiles := []e2e.Profile{
    	e2e.UserProfile, 
    	e2e.RootProfile, 
    	e2e.FakerootProfile, 
    	e2e.UserNamespaceProfile,
  }

	for _, p := range profiles {
		c.env.RunSingularity(
			t,
			e2e.AsSubtest(p.String()),
			e2e.WithProfile(p),
			e2e.WithCommand("exec"),
			e2e.WithArgs("--sif-fuse=false", "--no-tmp-sandbox", "-u", c.env.ImagePath, "/bin/true"),
			e2e.ExpectExit(255),
		)
	}
}
```

--------------------------------

### Run Singularity Container with Version Argument

Source: https://github.com/sylabs/singularity/blob/main/examples/build-singularity/README.md

Execute the built Singularity container, passing the desired Singularity version as an argument.

```shell
./build-singularity.sif {version}
```

```shell
./build-singularity.sif 3.6.2
```

--------------------------------

### Create AppArmor profile for SingularityCE

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Creates a profile at /etc/apparmor.d/singularity-ce to permit unprivileged user namespace creation. Adjust the path if a non-default prefix was used.

```sh
sudo tee /etc/apparmor.d/singularity-ce << 'EOF'
# Permit unprivileged user namespace creation for SingularityCE starter
abi <abi/4.0>,
include <tunables/global>

profile singularity-ce /usr/local/libexec/singularity/bin/starter{,-suid} flags=(unconfined) {
  userns,

  # Site-specific additions and overrides. See local/README for details.
  include if exists <local/singularity-ce>
}
EOF
```

--------------------------------

### Add Help Text to Testdata

Source: https://github.com/sylabs/singularity/blob/main/e2e/help/README.md

Redirect the output of `singularity help inspect` to a file in the testdata directory to capture the help text for testing.

```sh
singularity help inspect > e2e/testdata/help/help-inspect.txt
```

--------------------------------

### Create Test Group Directory

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Create a new directory for your test group within the `e2e` directory.

```sh
mkdir -p e2e/env
```

--------------------------------

### Declare Test Group Package

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Add a package declaration to your test file that matches the entry in `suite.go`.

```go
package env
```

--------------------------------

### Using e2e.ExpectExit() with e2e.ExpectOutput()

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

This snippet demonstrates how to use e2e.ExpectExit() to verify a successful CLI run (exit code 0) and exact stdout content. It requires the output to be exactly 'BAR' with a terminating newline.

```go
e2e.ExpectExit(
    0,
    e2e.ExpectOutput(e2e.ExactMatch, "BAR"),
)
```

--------------------------------

### Project Directory Structure

Source: https://github.com/sylabs/singularity/blob/main/AGENTS.md

Visual representation of the Singularity source code repository layout.

```text
singularity
├── .circleci                              # CircleCI CI/CD configuration
├── builddir                               # Generated build files
├── cmd                                    # Top-level CLI code
│   ├── bash_completion                    # Bash completions generator
│   ├── docs                               # man / markdown CLI docs generator
│   ├── internal
│   │   └── cli                            # singularity CLI Cobra commands
│   ├── singularity                        # Main singularity CLI entry-point
│   ├── singularity-buildkitd              # Customised buildkitd executable for Dockerfile builds
│   └── starter                            # Runtime starter entry-point
├── debian                                 # Deb packaging for Ubuntu
├── dist
│   └── rpm                                # RPM packaging for RHEL / AlmaLinux / Rocky Linux
├── docs                                   # CLI docstrings
├── e2e                                    # End-to-end test suite
├── etc                                    # Template configuration files
├── examples                               # Example container definition files
├── internal
│   ├── app
│   │   ├── singularity                    # singularity CLI implementation
│   │   └── starter                        # Runtime starter implementation
│   └── pkg                                # Private runtime, image, utility, etc. packages.
├── makeit                                 # makeit Makefile generator tool
├── mlocal                                 # Checks and templates for ./mconfig build configuration
├── pkg                                    # Public types and utility packages.
├── scripts                                # Build, test, development wrapper scripts
├── test                                   # Test fixtures
└── third_party                            # Third-party software
```

--------------------------------

### Creating a Distribution Tarball

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Generate a local distribution tarball for release. This involves cleaning the build directory, configuring the build with the correct version, and creating the tarball.

```bash
git clean -fdx && ./mconfig -v && make -C builddir dist
```

--------------------------------

### Add Help Command to Struct

Source: https://github.com/sylabs/singularity/blob/main/e2e/help/README.md

Add the `help inspect` command to the `helpContentTests` struct in `help.go` to include it in the test suite.

```go
var helpContentTests = []struct {
        cmds []string
}{
        ...
        // singularity inspect
        {[]string{"help", "inspect"}},
        ...
}
```

--------------------------------

### Self Bootstrap Specifying Root

Source: https://github.com/sylabs/singularity/blob/main/examples/self/README.md

Optionally, you can specify the root directory for the self bootstrap using the 'From' directive. This is typically set to '/' for the current system's root.

```text
Bootstrap: self
From: /
```

--------------------------------

### Table-Driven Tests for Exit Signals

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Demonstrates using an inline struct array to define multiple test cases for checking different exit signals from Singularity commands. Each struct defines arguments and the expected exit code, allowing for concise test execution within a loop.

```go
func (c actionTests) exitSignals(t *testing.T) {
	e2e.EnsureImage(t, c.env)

	tests := []struct {
		name string
		args []string
		exit int
	}{
		{
			name: "Exit0",
			args: []string{c.env.ImagePath, "/bin/sh", "-c", "exit 0"},
			exit: 0,
		},
		{
			name: "Exit1",
			args: []string{c.env.ImagePath, "/bin/sh", "-c", "exit 1"},
			exit: 1,
		},
		{
			name: "Exit134",
			args: []string{c.env.ImagePath, "/bin/sh", "-c", "exit 134"},
			exit: 134,
		},
		{
			name: "SignalKill",
			args: []string{c.env.ImagePath, "/bin/sh", "-c", "kill -KILL $$"},
			exit: 137,
		},
		{
			name: "SignalAbort",
			args: []string{c.env.ImagePath, "/bin/sh", "-c", "kill -ABRT $$"},
			exit: 134,
		},
	}

	for _, tt := range tests {
		c.env.RunSingularity(
			t,
			e2e.AsSubtest(tt.name),
			e2e.WithProfile(e2e.UserProfile),
			e2e.WithCommand("exec"),
			e2e.WithArgs(tt.args...),
			e2e.ExpectExit(tt.exit),
		)
	}
}
```

--------------------------------

### Declare E2ETests Function

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Create a public `E2ETests` function that initializes the context and returns a `testhelper.Tests` struct containing your test methods.

```go
func E2ETests(env e2e.TestEnv) testhelper.Tests {
    c := ctx{
        env: env,
    }

    return testhelper.Tests{
        "environment echo": c.echoEnv,
    }
}
```

--------------------------------

### Run All E2E Tests

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Execute all end-to-end tests using the `e2e-test` make target.

```sh
make -C builddir e2e-test
```

--------------------------------

### Self Bootstrap with Exclusions

Source: https://github.com/sylabs/singularity/blob/main/examples/self/README.md

To optimize image size, use the 'Exclude' directive to prevent specific directories or patterns from being included in the container. This is useful for excluding large or unnecessary data like Docker storage.

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

--------------------------------

### Singularity Registry Login

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Logs into a Singularity registry using provided credentials and an authfile. Use this command to authenticate with a remote registry.

```bash
/usr/local/bin/singularity registry login --authfile ./my_local_authfile -u e2e -p e2e docker://localhost:41151
```

--------------------------------

### Define and Run Singularity E2E Subtests

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Defines a slice of test cases, each with a name, profile, command, arguments, and expected exit code. It then iterates through these tests, running each as a subtest using `c.env.RunSingularity` with various configurations.

```go
tests := []struct {
		name       string
		profile    e2e.Profile
		command    string
		args       []string
		expectExit int
	}{
		{
			name:       "Install",
			profile:    e2e.RootProfile,
			command:    "plugin install",
			args:       []string{sifFile},
			expectExit: 0,
		},
		{
			name:       "CLICallback",
			profile:    e2e.UserProfile,
			command:    "exit",
			args:       []string{"42"},
			expectExit: 42,
		},
		{
			name:       "SingularityConfigCallback",
			profile:    e2e.UserProfile,
			command:    "shell",
			args:       []string{c.env.TestDir},
			expectExit: 43,
		},
		{
			name:       "Uninstall",
			profile:    e2e.RootProfile,
			command:    "plugin uninstall",
			args:       []string{pluginName},
			expectExit: 0,
		},
	}

	for _, tt := range tests {
		c.env.RunSingularity(
			t,
			e2e.AsSubtest(tt.name),
			e2e.WithProfile(tt.profile),
			e2e.WithCommand(tt.command),
			e2e.WithArgs(tt.args...),
			e2e.ExpectExit(tt.expectExit),
		)
	}
}
```

--------------------------------

### Conditional Cleanup of Temporary Directory

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Demonstrates how to conditionally clean up a temporary directory based on test success. The cleanup function returned by `e2e.MakeTempDir` is deferred, but only executed if the test has not failed.

```go
	tmpDir, cleanup := e2e.MakeTempDir(t, c.env.TestDir, "oci_overlay_teardown-", "")
	t.Cleanup(func() {
		if !t.Failed() {
			cleanup(t)
		}
	})
```

--------------------------------

### Run Singularity Command in VM

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Execute a Singularity command within the VM. Your home directory is automatically shared.

```shell
singularity run library://alpine
```

--------------------------------

### Stop SingularityCE VM

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Command to gracefully stop the running SingularityCE virtual machine.

```shell
limactl stop singularity-ce
```

--------------------------------

### Run Arch Linux Docker Image

Source: https://github.com/sylabs/singularity/blob/main/examples/arch/README.md

Initiates an interactive bash session within a Docker Arch Linux container. This is useful for setting up the build environment on a non-Arch host.

```bash
docker run -it  --privileged pritunl/archlinux bash
```

--------------------------------

### Combine Profile Iteration with Table-Driven Tests

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Nest a table-driven test within a loop that iterates over profiles. This allows testing multiple scenarios (defined in the table) across different user profiles, ensuring consistent behavior. Use t.Run for each profile to avoid test name collisions.

```go
func (c *ctx) testInstanceAuthFile(t *testing.T) {
	e2e.EnsureORASImage(t, c.env)
	instanceName := "actionAuthTesterInstance"
	localAuthFileName := "./my_local_authfile"
	authFileArgs := []string{"--authfile", localAuthFileName}

  <...>

	tests := []struct {
		name          string
		subCmd        string
		args          []string
		whileLoggedIn bool
		expectExit    int
	}{
		{
			name:          "start before auth",
			subCmd:        "start",
			args:          append(authFileArgs, "--disable-cache", "--no-https", c.env.TestRegistryPrivImage, instanceName),
			whileLoggedIn: false,
			expectExit:    255,
		},
		{
			name:          "start",
			subCmd:        "start",
			args:          append(authFileArgs, "--disable-cache", "--no-https", c.env.TestRegistryPrivImage, instanceName),
			whileLoggedIn: true,
			expectExit:    0,
		},
		{
			name:          "stop",
			subCmd:        "stop",
			args:          []string{instanceName},
			whileLoggedIn: true,
			expectExit:    0,
		},
		{
			name:          "start noauth",
			subCmd:        "start",
			args:          append(authFileArgs, "--disable-cache", "--no-https", c.env.TestRegistryPrivImage, instanceName),
			whileLoggedIn: false,
			expectExit:    255,
		},
	}

	profiles := []e2e.Profile{
		e2e.UserProfile,
		e2e.RootProfile,
	}

	for _, p := range profiles {
		t.Run(p.String(), func(t *testing.T) {
			for _, tt := range tests {
				if tt.whileLoggedIn {
					e2e.PrivateRepoLogin(t, c.env, p, localAuthFileName)
				} else {
					e2e.PrivateRepoLogout(t, c.env, p, localAuthFileName)
				}
				c.env.RunSingularity(
					t,
					e2e.AsSubtest(tt.name),
					e2e.WithProfile(p),
					e2e.WithCommand("instance "+tt.subCmd),
					e2e.WithArgs(tt.args...),
					e2e.ExpectExit(tt.expectExit),
				)
			}
		})
	}
}
```

--------------------------------

### Apply and Push Annotated Tag for Release Candidate

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Apply an annotated Git tag for a release candidate and push it to the remote repository.

```bash
git tag -a -m "SingularityCE v3.11.0 Release Candidate 1" v3.11.0-rc.1
git push upstream v3.11.0-rc.1
```

--------------------------------

### Run Singularity Directly with Homedir Mount

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Execute a Singularity command directly from your macOS host, ensuring your home directory is mounted using the -H flag.

```shell
limactl shell singularity-ce singularity run -H /Users/myuser library://alpine
```

--------------------------------

### Enable repository for RHEL/Alma/Rocky

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Enables the CRB or powertools repository required for building on RHEL-based systems.

```sh
sudo dnf install -y dnf-plugins-core
sudo dnf config-manager --enable crb || dnf config-manager --enable powertools
```

--------------------------------

### Clone Singularity Source Code

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Obtain the Singularity source code matching your binary version to compile the plugin.

```bash
git clone https://github.com/sylabs/singularity.git
cd singularity
git checkout 7998470e7
```

--------------------------------

### Apply and Push Annotated Tag for Final Release

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Apply an annotated Git tag for a final release and push it to the remote repository.

```bash
git tag -a -m "SingularityCE v3.12.0" v3.12.0
git push upstream v3.12.0
```

--------------------------------

### Inspect a Specific App in Singularity Image

Source: https://github.com/sylabs/singularity/blob/main/examples/apps/README.md

Inspect the metadata or configuration of a specific application within a Singularity image. This can reveal details like app name and size.

```console
$ singularity inspect --app fortune cowsay.img 
{
    "SCIF_APPNAME": "fortune",
    "SCIF_APPSIZE": "1MB"
}
```

--------------------------------

### Run Singularity Directly from Host

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Execute a Singularity command directly from your macOS host, targeting the VM. This is a shortcut for entering the shell and running the command.

```shell
limactl shell singularity-ce singularity run library://alpine
```

--------------------------------

### Configure FUSE mounts for AppArmor

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Adds a rule to the local fusermount3 profile to allow FUSE mounts on Ubuntu 26.04+.

```sh
echo "umount /usr/local/var/singularity/**/," >> /etc/apparmor.d/local/fusermount3
```

--------------------------------

### Run Singularity with Explicit Homedir Mount

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

When running Singularity commands interactively, explicitly specify your macOS homedir using the -H flag if it's not automatically mounted as expected.

```shell
singularity run -H /Users/myuser library://alpine
```

--------------------------------

### Run End-to-End Tests

Source: https://github.com/sylabs/singularity/blob/main/AGENTS.md

Use the scripts/e2e-test wrapper to execute specific sequential or parallel test groups.

```sh
# After configure, build, and install steps in Quick Start

# Sequential e2e tests using testhelper.NoParallel
scripts/e2e-test -v -run TestE2E/SEQ/<GROUP>/<NAME>

# Example
scripts/e2e-test -v -run TestE2E/SEQ/ACTIONS/umask

# Parallel e2e tests
scripts/e2e-test -v -run TestE2E/PAR/<GROUP>/<NAME>

# Example
scripts/e2e-test -v -run TestE2E/PAR/ACTIONS/shell
```

--------------------------------

### Define Context Struct for Tests

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Declare a context struct that embeds `e2e.TestEnv` and can hold additional group-specific variables.

```go
type ctx struct {
    env e2e.TestEnv
}
```

--------------------------------

### Enable Disabled Plugin

Source: https://github.com/sylabs/singularity/blob/main/examples/plugins/cli-plugin/README.md

Enable a previously disabled Singularity plugin by its name.

```bash
singularity plugin enable sylabs.io/cli-plugin
```

--------------------------------

### Declare E2ETests Group in suite.go

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Add your test group to the `e2eGroups` map in `suite.go`. Use `e2eGroupsNoPIDNS` only for tests that cannot run within a PID namespace.

```go
var e2eGroups = map[string]testhelper.Group{
    ...
    "ENV":        env.E2ETests,
}
```

--------------------------------

### Run E2E Tests by Name (Regex)

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Filter E2E tests by name using a regular expression provided to the `E2E_TESTS` environment variable.

```sh
# Only run e2e tests with a name that begins with 'semantic'
make -C builddir e2e-test E2E_TESTS=^semantic
```

--------------------------------

### Delete SingularityCE VM

Source: https://github.com/sylabs/singularity/blob/main/examples/lima/README.md

Command to remove the SingularityCE virtual machine and all its associated data.

```shell
limactl delete singularity-ce
```

--------------------------------

### Combine E2E Group and Test Name Filtering

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Combine `E2E_GROUPS` and `E2E_TESTS` environment variables to run E2E tests that belong to specific groups and match a given name pattern.

```sh
# Only run e2e tests in the VERSION group that have a name that begins with 'semantic'
make -C builddir e2e-test E2E_GROUPS=VERSION E2E_TESTS=^semantic
```

--------------------------------

### Pushing a Patch Release Tag

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Push the newly created annotated tag to the upstream GitHub repository to make it available remotely.

```git
git push upstream v3.11.3
```

--------------------------------

### Merge Release Branch into Main

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Merge the release branch into the main branch to incorporate changes from the release process.

```bash
git checkout main
git merge release-3.12
git push origin main
```

--------------------------------

### Update submodules

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Use this if the repository was cloned without submodules.

```sh
git submodule update --init
```

--------------------------------

### Tagging a Patch Release

Source: https://github.com/sylabs/singularity/blob/main/RELEASE_PROCEDURE.md

Apply an annotated Git tag to the HEAD of the release branch for a patch release. Ensure the tag message accurately reflects the version being released.

```git
git tag -a -m "SingularityCE v3.11.3" v3.11.3
```

--------------------------------

### Singularity Registry Logout

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Logs out from a Singularity registry using the specified authfile. This command revokes the current registry session.

```bash
/usr/local/bin/singularity registry logout --authfile ./my_local_authfile docker://localhost:41151
```

--------------------------------

### Run E2E Tests by Group

Source: https://github.com/sylabs/singularity/blob/main/e2e/README.md

Filter E2E tests to run only those within specified groups by setting the `E2E_GROUPS` environment variable.

```sh
# Only run tests in the VERSION and HELP groups
make -C builddir e2e-test E2E_GROUPS=VERSION,HELP
```

--------------------------------

### Reload AppArmor profiles

Source: https://github.com/sylabs/singularity/blob/main/INSTALL.md

Applies changes to AppArmor profiles.

```sh
sudo systemctl reload apparmor
```

--------------------------------

### Rebuild Container with Version Fix

Source: https://github.com/sylabs/singularity/blob/main/examples/build-singularity/README.md

Modify this statement when rebuilding the container if Singularity versions contain the character 'v'.

```shell
curl -L -o singularity-${VERSION}.tar.gz \
  https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-${VERSION}.tar.gz
```
Tokens:
Raw