User Guide

Welcome to the Singularity User Guide!

This guide aims to give an introduction to Singularity, brief installation instructions, and cover topics relevant to users building and running containers.

For a detailed guide to installation and configuration, please see the separate Admin Guide for this version of Singularity at https://singularity.hpcng.org/admin-docs/3.8/.

Getting Started & Background Information

• Introduction to Singularity
  • Why use Singularity?
  • Why use containers?
  • Use Cases
• Quick Start
  • Quick Installation Steps
  • Overview of the Singularity Interface
  • Download pre-built images
  • Interact with images
  • Working with Files
  • Build images from scratch
• Security in Singularity
  • Security Policy
  • Singularity PRO - Long Term Support & Security Patches
  • Singularity Runtime & User Privilege
  • Singularity Image Format (SIF)
  • Admin Configurable Files
  • Security in the Sylabs Cloud

Building Containers

• Build a container
  • Overview
  • Downloading an existing container from the Container Library
  • Downloading an existing container from Docker Hub
  • Creating writable --sandbox directories
  • Converting containers from one format to another
  • Building containers from Singularity definition files
  • Building encrypted containers
  • Build options
    • --builder
    • --detached
    • --encrypt
    • --fakeroot
    • --force
    • --json
    • --library
    • --notest
    • --passphrase
    • --pem-path
    • --remote
    • --sandbox
    • --section
    • --update
    • --nv
    • --rocm
    • --bind
  • More Build topics
• The Definition File
  • Overview
  • Header
    • Preferred bootstrap agents
    • Other bootstrap agents
    • SIF Image Verification / Fingerprints Header
  • Sections
    • %setup
    • %files
    • %app*
    • %post
    • %test
    • %environment
    • %startscript
    • %runscript
    • %labels
    • %help
  • Multi-Stage Builds
  • Apps
  • Best Practices for Build Recipes
• Build Environment
  • Overview
  • Cache Folders
  • Cache commands
    • Listing Cache
    • Cleaning the Cache
  • Temporary Folders
  • Encrypted Containers
  • Environment Variables
    • Defaults
• Singularity and Docker
  • Overview
  • Running action commands on public images from Docker Hub
  • Making use of public images from Docker Hub
  • Making use of private images from Docker Hub
    • Authentication via Remote Login
    • Authentication via Interactive Login
    • Authentication via Environment Variables
  • Making use of private images from Private Registries
  • Building images for Singularity from Docker Registries
    • Working from the Singularity Command Line
    • Working with Definition Files
  • OCI Image Support
    • Overview
    • Building Containers for Singularity from OCI Images
  • Container Caching
  • Best Practices
  • Troubleshooting
  • Singularity Definition file vs. Dockerfile
• Fakeroot feature
  • Overview
  • Restrictions/security
    • Filesystem
    • Network
  • Requirements / Configuration
  • Usage
    • Build
    • Examples

Signing & Encryption

• Sign and Verify
  • Verifying containers from the Container Library
  • Signing your own containers
• Key management commands
  • Changes in Singularity 3.7
  • Key import command
  • Key export command
  • Key remove command
• Encrypted Containers
  • Overview
  • Encrypting a container
  • Running an encrypted container

Sharing & Online Services

• Remote Endpoints
  • Overview
  • Public Sylabs Cloud
  • Managing Remote Endpoints
  • Keyserver Configurations
  • Managing OCI Registries
• Cloud Library
  • Overview
  • Make an Account
  • Creating a Access token
  • Pushing a Container
  • Pulling a container
  • Verify/Sign your Container
  • Searching the Library for Containers
  • Remote Builder

Advanced Usage

• Bind Paths and Mounts
  • Overview
  • System-defined bind paths
  • User-defined bind paths
  • FUSE mounts
  • Image Mounts
• Persistent Overlays
  • Overview
  • Usage
• Running Services
  • Overview
  • Container Instances in Singularity
  • Nginx “Hello-world” in Singularity
  • Putting all together
  • System integration / PID files
• Environment and Metadata
  • Changes in Singularity 3.6
  • Environment Overview
  • Environment from a base image
  • Environment from a definition file
  • Environment from the host
  • Environment from the Singularity runtime
  • Overriding environment variables
  • Umask / Default File Permissions
  • Container Metadata
  • /.singularity.d directory
• OCI Runtime Support
  • Overview
  • Mounted OCI Filesystem Bundles
  • Creating OCI Compliant Container Instances
  • Unmounting OCI Filesystem Bundles
  • Kubernetes Integration
• Plugins
  • Overview
  • Using Plugins
  • Writing a Plugin
• Security Options
  • Linux Capabilities
  • Building encrypted containers
  • Security related action options
• Network Options
  • --dns
  • --hostname
  • --net
  • --network
  • --network-args
• Cgroups Support
  • Overview
  • Examples
• Singularity and MPI applications
  • Hybrid model
  • Bind model
  • Batch Scheduler / Slurm
  • Alternative Launchers
  • Interconnects / Networking
  • Troubleshooting Tips
• GPU Support
  • NVIDIA GPUs & CUDA
  • AMD GPUs & ROCm
  • OpenCL Applications

Get Involved

• Contributing
  • Join the community
  • Raise an Issue
  • Write Documentation
  • Contribute to the code

Reference

• Appendix
  • Singularity’s environment variables
  • Build Modules
• Command Line Reference
  • singularity
  • singularity build
  • singularity cache
  • singularity cache clean
  • singularity cache list
  • singularity capability
  • singularity capability add
  • singularity capability avail
  • singularity capability drop
  • singularity capability list
  • singularity config
  • singularity config fakeroot
  • singularity config global
  • singularity delete
  • singularity exec
  • singularity inspect
  • singularity instance
  • singularity instance list
  • singularity instance start
  • singularity instance stop
  • singularity key
  • singularity key export
  • singularity key import
  • singularity key list
  • singularity key newpair
  • singularity key pull
  • singularity key push
  • singularity key remove
  • singularity key search
  • singularity oci
  • singularity oci attach
  • singularity oci create
  • singularity oci delete
  • singularity oci exec
  • singularity oci kill
  • singularity oci mount
  • singularity oci pause
  • singularity oci resume
  • singularity oci run
  • singularity oci start
  • singularity oci state
  • singularity oci umount
  • singularity oci update
  • singularity overlay
  • singularity overlay create
  • singularity plugin
  • singularity plugin compile
  • singularity plugin create
  • singularity plugin disable
  • singularity plugin enable
  • singularity plugin inspect
  • singularity plugin install
  • singularity plugin list
  • singularity plugin uninstall
  • singularity pull
  • singularity push
  • singularity remote
  • singularity remote add
  • singularity remote add-keyserver
  • singularity remote list
  • singularity remote login
  • singularity remote logout
  • singularity remote remove
  • singularity remote remove-keyserver
  • singularity remote status
  • singularity remote use
  • singularity run
  • singularity run-help
  • singularity search
  • singularity shell
  • singularity sif
  • singularity sif add
  • singularity sif del
  • singularity sif dump
  • singularity sif header
  • singularity sif info
  • singularity sif list
  • singularity sif new
  • singularity sif setprim
  • singularity sign
  • singularity test
  • singularity verify
  • singularity version
• License