How to Use the Command 'Singularity' (with Examples)

Singularity is a container platform focused on supporting reproducibility, mobility of compute, and the use of containers in high-performance computing (HPC) environments. It allows for managing, developing, and running containerized applications seamlessly. By using Singularity, users can create isolated environments that encapsulate their application dependencies and leverage the powerful computing resources across varied infrastructure.

Use Case 1: Download a Remote Image from Sylabs Cloud

Code:

singularity pull --name image.sif library://godlovedc/funny/lolcow:latest

Motivation:

This use case comes in handy when you need to pull a pre-built container image from a remote library, such as Sylabs Cloud, which is a common hub for sharing and storing Singularity images. Accessing images directly from an established library allows you to use or customize applications maintained by other developers, saving you significant effort and time in developing from scratch.

Explanation:

• singularity pull: This command pulls or downloads a singularity image from a specified location.
• --name image.sif: This option specifies the name you want for the downloaded image file. In this case, image.sif is the desired name of the local copy.
• library://godlovedc/funny/lolcow:latest: This is the identifier of the image in Sylabs Cloud that you wish to download. It includes the owner (godlovedc), the collection (funny), the image name (lolcow), and the version (latest).

Example Output:

INFO: Downloading library image
INFO: Download complete: image.sif

Use Case 2: Rebuild a Remote Image Using the Latest Singularity Image Format

Code:

singularity build image.sif docker://godlovedc/lolcow

Motivation:

When you come across a Docker image that serves your needs but want to use it in environments where Singularity is preferred or a necessity, converting or rebuilding the image to the Singularity format is essential. This maintains compatibility across different container ecosystems and enables better integration into HPC workflows.

Explanation:

• singularity build: This command builds a new Singularity image using the source image specified.
• image.sif: This argument specifies the name of the resultant Singularity image file.
• docker://godlovedc/lolcow: This indicates that the image should be retrieved from Docker Hub, using a URI format that specifies the provider (docker://), the user or organization (godlovedc), and the image (lolcow).

Example Output:

INFO: Starting build from Docker
INFO: Building Singularity image...
INFO: Image built successfully: image.sif

Use Case 3: Start a Container from an Image and Get a Shell Inside It

Code:

singularity shell image.sif

Motivation:

Obtaining an interactive shell within a containerized environment is crucial for exploratory tasks, debugging, and understanding the tools and dependencies packaged within the container. This allows users to interactively test software within the same configuration as the final deployment, ensuring consistent behavior across testing and production environments.

Explanation:

• singularity shell: This command opens an interactive shell session within the environment encapsulated by the specified Singularity image.
• image.sif: This is the name of the Singularity image file that acts as the root filesystem for the shell session.

Example Output:

Singularity image.sif:~>

At this point, you are inside the container environment and have shell access to it.

Use Case 4: Start a Container from an Image and Run a Command

Code:

singularity exec image.sif command

Motivation:

Automating tasks by running specific commands within a container is central to utilizing Singularity for workflows and scripting purposes. This use case allows users to directly execute applications or scripts packaged within a container without additional shell modification, which is useful for scripting, batch processing, and job scheduling in HPC.

Explanation:

• singularity exec: This command allows for executing a specified command within the environment defined by a Singularity image.
• image.sif: This specifies the Singularity image to use as the execution context.
• command: This can be any executable or script that you wish to run within the container.

Example Output:

Output of the executed command

This output is the result of whatever command you specified in the place of command.

Use Case 5: Start a Container from an Image and Execute the Internal Runscript

Code:

singularity run image.sif

Motivation:

Running a built-in script or entrypoint defined in a container simplifies user interaction with complex software packages. This feature relies on an internal script specified when creating the Singularity image, allowing users to automatically run pre-defined tasks without defining them again at the command line.

Explanation:

• singularity run: This command executes the runscript embedded within the Singularity image, intended to be the main action or program of the container.
• image.sif: This is the Singularity image file containing the defined runscript to be executed.

Example Output:

Output of the default runscript

The result will depend on the runscript’s functionality defined within the image.

Use Case 6: Build a Singularity Image from a Recipe File

Code:

sudo singularity build image.sif recipe

Motivation:

Building an image from a recipe file allows users to define custom images tailored to their needs, encapsulating specific applications and dependencies. Recipes facilitate reproducibility by clearly specifying the build process, installing packages, setting environment variables, and copying files into the image.

Explanation:

• sudo: Root privileges are often necessary for the build operation to ensure complete access to system resources and permissions for all dependencies.
• singularity build: The command constructs a new Singularity image based on instructions from a recipe.
• image.sif: This names the built image file resulting from the recipe.
• recipe: This file contains the directives to build the image, akin to a Dockerfile, detailing the base image, packages, and configuration.

Example Output:

INFO: Using recipe...
INFO: Building Singularity recipe
INFO: Image build complete: image.sif

Conclusion

Singularity provides a comprehensive suite of tools for managing and executing containerized applications, especially in contexts where high-performance computing resources are involved. The command offers flexibility in creating, converting, and running containers, thereby enhancing reproducibility and portability across varied computing environments. From downloading shared images to building bespoke applications, Singularity addresses the needs of scientific computing and beyond.