Basics of Singularity

Singularity is a container platform designed for High Performance Computing (HPC), where Docker often can't run due to security and multi-user concerns. Singularity allows you to use containers on clusters, preserving reproducibility and portability.

Transitioning from Docker to Singularity

  • Docker: Requires root privileges, runs a daemon, not suited for multi-user HPC systems.
  • Singularity: Runs containers as the calling user (no root needed), integrates with HPC schedulers, supports direct use of Docker images.

Good news: You can use most Docker images directly with Singularity!

# Pull a Docker image as a Singularity image
singularity pull docker://ubuntu:22.04
# Runs as a .sif file (Singularity Image Format)

Installing and Loading Singularity on ARC/Great Lakes

# On ARC clusters, load the singularity module
module load singularity

Tip: Check ARC Container Guide for latest instructions.

Basic Singularity Usage

Running a Container

singularity run ubuntu_22.04.sif

Shell Into a Container

singularity shell ubuntu_22.04.sif

Execute a Command

singularity exec ubuntu_22.04.sif python3 --version

Bind Mounts: Accessing Host Data

By default, Singularity binds your $HOME and /tmp directories into the container. You can bind additional directories using the --bind option:

OptionUsageNotes
--bind /host/path:/container/pathBinds /host/path to /container/path inside the containerYou can specify multiple binds, comma-separated.
singularity exec --bind /scratch/yourdir:/mnt ubuntu_22.04.sif ls /mnt
Tip: Use bind mounts to access data, scripts, or large datasets from the host file system.

Namespaces in Singularity

Namespaces isolate aspects of the operating system for containers:

  • Process Namespace: Isolates running processes inside the container.
  • Mount Namespace: Controls what filesystems are visible.
  • Network Namespace: (Limited in Singularity) Controls network stack isolation.

Singularity uses these to ensure your containerized application runs independently from others and the host. 

Example Use Case: Running vLLM in Singularity

Step 1: Find a Docker Image for vLLM

Search for a suitable vLLM Docker image on Docker Hub or from vLLM's official docs.

Step 2: Pull the Docker Image as a Singularity Image

# Replace 'vllm/vllm:latest' with the actual image name
singularity pull docker://vllm/vllm:latest

Step 3: Run vLLM via Singularity

singularity exec --bind /path/to/data:/data vllm_latest.sif python3 -m vllm.entrypoints.openai.api_server --model /data/model

Step 4: Using GPUs (if available)

singularity exec --nv vllm_latest.sif python3 -m vllm.entrypoints.openai.api_server --model /data/model
For GPU support, use --nv (NVIDIA) or --rocm (AMD) options.

Summary: Docker vs. Singularity for HPC

  • Docker: Great for development, but not allowed on most HPC clusters.
  • Singularity: Designed for research and HPC, safe for shared environments.
  • You can convert and run Docker images with Singularity easily.
  • Bind mounts let you access host data from your container.
  • Namespaces keep your container isolated.

Further Reading