User Guide

• Quick Start
  • Quick Installation Steps
  • Overview of the Singularity Interface
  • Download pre-built images
  • Interact with images
    • Shell
    • Executing Commands
    • Running a container
    • Working with Files
  • Build images from scratch
    • Sandbox Directory
    • Writable Image
    • Converting images from one format to another
    • Singularity Recipes
• Introduction
  • Welcome to Singularity!
    • Mobility of Compute
    • Reproducibility
    • User Freedom
    • Support on Existing Traditional HPC
  • A High Level View of Singularity
    • Security and privilege escalation
    • The Singularity container image
      • Copying, sharing, branching, and distributing your image
      • Supported container formats
      • Supported Uniform Resource Identifiers (URI)
    • Name-spaces and isolation
    • Compatibility with standard work-flows, pipes and IO
    • The Singularity Process Flow
  • The Singularity Usage Workflow
    • Singularity Commands
  • Support
  • About
    • Overview
    • Background
      • The Singularity Solution
      • Portability and Reproducibility
    • Features
      • Encapsulation of the environment
      • Containers are image based
      • No user contextual changes or root escalation allowed
      • No root owned daemon processes
    • Use Cases
      • BYOE: Bring Your Own Environment
      • Reproducible science
      • Static environments (software appliances)
      • Legacy code on old operating systems
      • Complicated software stacks that are very host specific
      • Complicated work-flows that require custom installation and/or data
    • License
    • Getting started
• Installation
  • Before you begin
  • Install from a tag
  • Install a specific release
  • Install the development branch
  • Remove an old version
  • Install on Windows
    • Setup
    • Singularity Vagrant Box
  • Install on Linux
    • Installation from Source
      • Option 1: Download latest stable release
      • Option 2: Download the latest development code
      • Prefix in special characters
      • Updating
    • Debian Ubuntu Package
      • Testing first with Docker
      • Adding the Mirror and installing
    • Build an RPM from source
    • Build an DEB from source
    • Install on your Cluster Resource
  • Install on Mac
    • Setup
    • Option 1: Singularity Vagrant Box
    • Option 2: Vagrant Box from Scratch (more advanced alternative)
  • Requesting an Installation
    • How do I ask for Singularity on my local resource?
    • Information Resources
      • Background
      • Security
      • Presentations
    • Installation Request
• Build a Container
  • Overview
  • Downloading a existing container from Singularity Hub
  • Downloading a existing container from Docker Hub
  • Creating --writable images and --sandbox directories
    • --writable
    • --sandbox
  • Converting containers from one format to another
  • Building containers from Singularity recipe files
    • --force
    • --section
    • --notest
    • --checks
  • More Build topics
• Build Environment
  • Cache Folders
  • Temporary Folders
  • Pull Folder
  • Environment Variables
  • Cache
    • Defaults
      • Docker
      • Singularity Hub
    • General
• Container Recipes
  • Overview
    • Header
    • Sections
      • %help
      • %setup
      • %files
      • %labels
      • %environment
      • %post
      • %runscript
      • %test
  • Apps
  • Examples
  • Best Practices for Build Recipes
• Singularity Flow
  • Building Images
    • The Singularity Flow
    • 1. Development Commands
      • Sandbox Folder
      • Writable Image
    • 2. Production Commands
      • Recommended Production Build
      • Production Build from Sandbox
• Bind Paths and Mounts
  • Overview
    • System-defined bind points
    • User-defined bind points
      • Specifying Bind Paths
      • Binding with Overlay
• Persistent Overlays
  • Overview
  • Usage
• Running Services
  • Why container instances?
  • Container Instances in Singularity
  • Nginx “Hello-world” in Singularity
  • Putting all together
    • Building the image
    • Running the Server
    • Making it Pretty
  • Important Notes
• Container Checks
  • Tags and Organization
  • What checks are available?
• Environment and Metadata
  • Environment
  • Labels
  • Container Metadata
• Reproducible SCI-F Apps
  • Why do we need SCI-F?
    • Mixed up Modules
    • Container Transparency
    • Container Modularity
    • Sections
    • Interaction
  • SCI-F Example: Cowsay Container
• Singularity and Docker
  • TLDR (Too Long Didn’t Read)
  • Import a Docker image into a Singularity Image
  • Quick Start: The Docker Registry
  • The Build Specification file, Singularity
  • How does the runscript work?
  • How do I specify my Docker image?
  • Custom Authentication
    • Authentication in the Singularity Build File
    • Authentication in the Environment
    • Testing Authentication
  • Best Practices
    • 1. Installation to Root
    • 2. Library Configurations
    • 3. Don’t install to $HOME or $TMP
  • Troubleshooting
• Troubleshooting
  • No space left on device
  • Segfault on Bootstrap of Centos Image
  • How to use Singularity with GRSecurity enabled kernels
  • The container isn’t working on a different host!
  • Invalid Argument or Unknown Option
  • Error running Singularity with sudo
  • How to resolve “Too many levels of symbolic links” error
• Appendix
  • build-docker-module
    • Overview
    • Keywords
    • Notes
  • build-shub
    • Overview
    • Keywords
    • Notes
  • build-localimage
    • Overview
    • Keywords
    • Notes
  • build-yum
    • Overview
    • Keywords
    • Notes
  • build-debootstrap
    • Overview
    • Keywords
    • Notes
  • build-arch
    • Overview
    • Keywords
    • Notes
  • build-busybox
    • Overview
    • Keywords
    • Notes
  • build-zypper
    • Overview
    • Keywords
  • Singularity Action Flags
    • Examples
  • Commands
    • Command Usage
      • The Singularity command
        • Options and argument processing
        • Singularity Help
      • Commands Usage
      • Support
    • build
      • Overview
      • Examples
        • Download an existing container from Singularity Hub or Docker Hub
        • Create –writable images and –sandbox directories
        • Convert containers from one format to another
        • Build a container from a Singularity recipe
    • exec
      • Examples
        • Printing the OS release inside the container
        • Printing the OS release for a running instance
        • Runtime Flags
        • Special Characters
        • A Python example
        • A GPU example
    • inspect
      • JSON Api Standard
      • Inspect Flags
        • Labels
        • Runscript
        • Help
        • Environment
        • Test
        • Deffile
    • pull
      • Singularity Hub
        • How do tags work?
        • Image Names
        • Custom Name
        • Name by commit
        • Name by hash
        • Pull to different folder
        • Pull by commit
      • Docker
    • run
      • Overview
      • Runtime Flags
      • Examples
        • Defining the Runscript
    • shell
      • Change your shell
        • Bash
      • Shell Help
  • Image Command Group
    • image.export
    • image.expand
      • Increasing the size of an existing image
    • image.import
    • image.create
      • Creating a new blank Singularity container image
        • Overwriting an image with a new one
  • Instance Command Group
    • instance.start
      • Overview
      • Examples
        • Start an instance called cow1 from a container on Singularity Hub
        • Start an interactive shell within the instance that you just started
        • Execute the runscript within the instance
        • Run a command within a running instance
    • instance.list
      • Overview
      • Examples
        • Start a few named instances from containers on Singularity Hub
        • List running instances
    • instance.stop
      • Overview
      • Examples
        • Start a few named instances from containers on Singularity Hub
        • Stop a single instance
        • Stop all running instances
  • Deprecated
    • bootstrap
      • Quick Start
• Contributing
  • Support Singularity
    • Singularity Google Group
    • Singularity on Slack
  • Contribute to the code
    • Step 1. Fork the repo
    • Step 2. Set up your config
    • Step 3. Checkout a new branch
    • Step 4. Make your changes
    • Step 5. Push your branch to your fork
    • Step 6. Submit a Pull Request
    • Support, helping and spreading the word!
  • Contributing to Documentation
• FAQ
  • General Singularity Info
    • Why the name “Singularity”?
    • What is so special about Singularity?
    • Which namespaces are virtualized? Is that select-able?
    • What Linux distributions are you trying to get on-board?
    • How do I request an installation on my resource?
  • Basic Singularity usage
    • Do you need administrator privileges to use Singularity?
    • What if I don’t want to install Singularity on my computer?
    • Can you edit/modify a Singularity container once it has been instantiated?
    • Can multiple applications be packaged into one Singularity Container?
    • How are external file systems and paths handled in a Singularity Container?
    • How does Singularity handle networking?
    • Can Singularity support daemon processes?
    • Can a Singularity container be multi-threaded?
    • Can a Singularity container be suspended or check-pointed?
    • Are there any special requirements to use Singularity through an HPC job scheduler?
    • Does Singularity work in multi-tenant HPC cluster environments?
    • Can I run X11 apps through Singularity?
    • Can I containerize my MPI application with Singularity and run it properly on an HPC system?
    • Why do we call ‘mpirun’ from outside the container (rather than inside)?
    • Does Singularity support containers that require GPUs?
  • Container portability
    • Are Singularity containers kernel-dependent?
    • Can a Singularity container resolve GLIBC version mismatches?
    • What is the performance trade off when running an application native or through Singularity?
  • Misc
    • Are there any special security concerns that Singularity introduces?