Installation

This document will guide you through the process of installing Singularity >= 3.4.0 via several different methods. (For instructions on installing earlier versions of Singularity please see earlier versions of the docs.)

Overview

Singularity runs on Linux natively and can also be run on Windows and Mac through virtual machines (VMs). Here we cover several different methods of installing Singularity (>=3.4.0) on Linux and also give methods for downloading and running VMs with Singularity pre-installed from Vagrant Cloud.

Install on Linux

Linux is the only operating system that can support containers because of kernel features like namespaces. You can use these methods to install Singularity on bare metal Linux or a Linux VM.

Before you begin

If you have an earlier version of Singularity installed, you should remove it before executing the installation commands. You will also need to install some dependencies and install Go.

Install Dependencies

Install these dependencies with apt-get or yum/rpm as shown below or similar with other package managers.

apt-get

$ sudo apt-get update && sudo apt-get install -y \
    build-essential \
    libssl-dev \
    uuid-dev \
    libgpgme11-dev \
    squashfs-tools \
    libseccomp-dev \
    wget \
    pkg-config \
    git \
    cryptsetup-bin

yum

$ sudo yum update -y && \
    sudo yum groupinstall -y 'Development Tools' && \
    sudo yum install -y \
    openssl-devel \
    libuuid-devel \
    libseccomp-devel \
    wget \
    squashfs-tools

Install Go

Singularity v3 is written primarily in Go, and you will need Go installed to compile it from source.

This is one of several ways to install and configure Go.

Visit the Go download page and pick a package archive to download. Copy the link address and download with wget. Then extract the archive to /usr/local (or use other instructions on go installation page).

$ export VERSION=1.12 OS=linux ARCH=amd64 && \
    wget https://dl.google.com/go/go$VERSION.$OS-$ARCH.tar.gz && \
    sudo tar -C /usr/local -xzvf go$VERSION.$OS-$ARCH.tar.gz && \
    rm go$VERSION.$OS-$ARCH.tar.gz

Then, set up your environment for Go.

$ echo 'export GOPATH=${HOME}/go' >> ~/.bashrc && \
    echo 'export PATH=/usr/local/go/bin:${PATH}:${GOPATH}/bin' >> ~/.bashrc && \
    source ~/.bashrc

Download Singularity from a release

You can download Singularity from one of the releases. To see a full list, visit the GitHub release page. After deciding on a release to install, you can run the following commands to proceed with the installation.

$ export VERSION=3.4.0 && # adjust this as necessary \
    wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-${VERSION}.tar.gz && \
    tar -xzf singularity-${VERSION}.tar.gz && \
    cd singularity

Download from source

The following commands will install Singularity from the GitHub repo to /usr/local. This method will work for >=v3.4.0. To install an older tagged release see older versions of the docs.

When installing from source, you can decide to install from either a tag, a release branch, or from the master branch.

• tag: GitHub tags form the basis for releases, so installing from a tag is the same as downloading and installing a specific release. Tags are expected to be relatively stable and well-tested.

• release branch: A release branch represents the latest version of a minor release with all the newest bug fixes and enhancements (even those that have not yet made it into a point release). For instance, to install v3.2 with the latest bug fixes and enhancements checkout release-3.2. Release branches may be less stable than code in a tagged point release.

• master branch: The master branch contains the latest, bleeding edge version of Singularity. This is the default branch when you clone the source code, so you don’t have to check out any new branches to install it. The master branch changes quickly and may be unstable.

To ensure that the Singularity source code is downloaded to the appropriate directory use these commands.

$ git clone https://github.com/sylabs/singularity.git && \
    cd singularity && \
    git checkout v3.4.0

Compile Singularity

Singularity uses a custom build system called makeit. mconfig is called to generate a Makefile and then make is used to compile and install.

$ ./mconfig && \
    make -C ./builddir && \
    sudo make -C ./builddir install

By default Singularity will be installed in the /usr/local directory hierarchy. You can specify a custom directory with the --prefix option, to mconfig like so:

$ ./mconfig --prefix=/opt/singularity

This option can be useful if you want to install multiple versions of Singularity, install a personal version of Singularity on a shared system, or if you want to remove Singularity easily after installing it.

For a full list of mconfig options, run mconfig --help. Here are some of the most common options that you may need to use when building Singularity from source.

• --sysconfdir: Install read-only config files in sysconfdir. This option is important if you need the singularity.conf file or other configuration files in a custom location.

• --localstatedir: Set the state directory where containers are mounted. This is a particularly important option for administrators installing Singularity on a shared file system. The --localstatedir should be set to a directory that is present on each individual node.

• -b: Build Singularity in a given directory. By default this is ./builddir.

Source bash completion file

To enjoy bash completion with Singularity commands and options, source the bash completion file like so. Add this command to your ~/.bashrc file so that bash completion continues to work in new shells. (Obviously adjust this path if you installed the bash completion file in a different location.)

$ . /usr/local/etc/bash_completion.d/singularity

Build and install an RPM

Building and installing a Singularty RPM allows the installation be more easily managed, upgraded and removed. In Singularity >=v3.0.1 you can build an RPM directly from the release tarball.

Note

Be sure to download the correct asset from the GitHub releases page. It should be named singularity-<version>.tar.gz.

After installing the dependencies and installing Go as detailed above, you are ready to download the tarball and build and install the RPM.

$ export VERSION=3.4.0 && # adjust this as necessary \
    wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-${VERSION}.tar.gz && \
    rpmbuild -tb singularity-${VERSION}.tar.gz && \
    sudo rpm -ivh ~/rpmbuild/RPMS/x86_64/singularity-$VERSION-1.el7.x86_64.rpm && \
    rm -rf ~/rpmbuild singularity-$VERSION*.tar.gz

If you encounter a failed dependency error for golang but installed it from source, build with this command:

rpmbuild -tb --nodeps singularity-${VERSION}.tar.gz

Options to mconfig can be passed using the familiar syntax to rpmbuild. For example, if you want to force the local state directory to /mnt (instead of the default /var) you can do the following:

rpmbuild -tb --define='_localstatedir /mnt' singularity-$VERSION.tar.gz

Note

It is very important to set the local state directory to a directory that physically exists on nodes within a cluster when installing Singularity in an HPC environment with a shared file system. Thus the _localstatedir option should be of considerable interest to HPC admins.

Remove an old version

In a standard installation of Singularity 3.0.1 and beyond (when building from source), the command sudo make install lists all the files as they are installed. You must remove all of these files and directories to completely remove Singularity.

Obviously, this list of files may differ depending on how you install Singularity or with newer versions of Singularity released following the writing of this document.

$ sudo rm -rf \
    /usr/local/libexec/singularity \
    /usr/local/var/singularity \
    /usr/local/etc/singularity \
    /usr/local/bin/singularity \
    /usr/local/bin/run-singularity \
    /usr/local/etc/bash_completion.d/singularity

If you anticipate needing to remove Singularity, it might be easier to install it in a custom directory using the --prefix option to mconfig. In that case Singularity can be uninstalled simply by deleting the parent directory. Or it may be useful to install Singularity using a package manager so that it can be updated and/or uninstalled with ease in the future.

Distribution packages of Singularity

Note

Packaged versions of Singularity in Linux distribution repos are maintained by community members. They (necessarily) tend to be older releases of Singularity. For the latest upstream versions of Singularity it is recommended that you build from source using one of the methods detailed above.

Install the Debian/Ubuntu package using apt

Singularity is available on Debian and derivative distributions starting with Debian stretch and the Ubuntu 16.10 releases. The package is called singularity-container. For more recent releases of singularity and backports for older Debian and Ubuntu releases, it is recommended that you use the NeuroDebian repository.

Enable the NeuroDebian repository following instructions on the NeuroDebian site. Use the dropdown menus to find the best mirror for your operating system and location. For example, after selecting Ubuntu 16.04 and selecting a mirror in CA, you are instructed to add these lists:

$ sudo wget -O- http://neuro.debian.net/lists/xenial.us-ca.full | sudo tee /etc/apt/sources.list.d/neurodebian.sources.list && \
    sudo apt-key adv --recv-keys --keyserver hkp://pool.sks-keyservers.net:80 0xA5D32F012649A5A9 && \
    sudo apt-get update

Now singularity can be installed like so:

sudo apt-get install -y singularity-container

During the above, if you have a previously installed configuration, you might be asked if you want to define a custom configuration/init, or just use the default provided by the package, eg:

Configuration file '/etc/singularity/init'

  ==> File on system created by you or by a script.
  ==> File also in package provided by package maintainer.
    What would you like to do about it ?  Your options are:
      Y or I  : install the package maintainer's version
      N or O  : keep your currently-installed version
        D     : show the differences between the versions
        Z     : start a shell to examine the situation
The default action is to keep your current version.
*** init (Y/I/N/O/D/Z) [default=N] ? Y

Configuration file '/etc/singularity/singularity.conf'
  ==> File on system created by you or by a script.
  ==> File also in package provided by package maintainer.
    What would you like to do about it ?  Your options are:
      Y or I  : install the package maintainer's version
      N or O  : keep your currently-installed version
        D     : show the differences between the versions
        Z     : start a shell to examine the situation
The default action is to keep your current version.
*** singularity.conf (Y/I/N/O/D/Z) [default=N] ? Y

Most users should accept these defaults. For cluster admins, we recommend that you read the admin docs to get a better understanding of the configuration file options available to you.

After following this procedure, you can check the Singularity version like so:

$ singularity --version
    2.5.2-dist

If you need a backport build of the recent release of Singularity on those or older releases of Debian and Ubuntu, you can see all the various builds and other information here.

Install the CentOS/RHEL package using yum

The epel (Extra Packages for Enterprise Linux) repos contain Singularity. The singularity package is actually split into two packages called singularity-runtime (which simply contains the necessary bits to run singularity containers) and singularity (which also gives you the ability to build Singularity containers).

To install Singularity from the epel repos, first install the repos and then install Singularity. For instance, on CentOS6/7 do the following:

$ sudo yum update -y && \
    sudo yum install -y epel-release && \
    sudo yum update -y && \
    sudo yum install -y singularity-runtime singularity

After following this procedure, you can check the Singularity version like so:

$ singularity --version
    2.6.0-dist

Install on Windows or Mac

Linux containers like Singularity cannot run natively on Windows or Mac because of basic incompatibilities with the host kernel. (Contrary to a popular misconception, Mac does not run on a Linux kernel. It runs on a kernel called Darwin originally forked from BSD.)

For this reason, the Singularity community maintains a set of Vagrant Boxes via Vagrant Cloud, one of Hashicorp’s open source tools. The current versions can be found under the sylabs organization.

Setup

First, install the following software:

Windows

Install the following programs:

• Git for Windows

• VirtualBox for Windows

• Vagrant for Windows

• Vagrant Manager for Windows

Mac

With Singularity Desktop for macOS (Alpha Preview):

The disk image file is available here. More information can be found here.

Singularity is also available via Vagrant (installable with Homebrew or manually) or with the Singularity Desktop for macOS (Alpha Preview).

With Homebrew:

$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
$ brew cask install virtualbox && \
    brew cask install vagrant && \
    brew cask install vagrant-manager

brew cask install vagrant-manager

Singularity Vagrant Box

Run GitBash (Windows) or open a terminal (Mac) and create and enter a directory to be used with your Vagrant VM.

$ mkdir vm-singularity && \
    cd vm-singularity

If you have already created and used this folder for another VM, you will need to destroy the VM and delete the Vagrantfile.

$ vagrant destroy && \
    rm Vagrantfile

Then issue the following commands to bring up the Virtual Machine. (Substitute a different value for the $VM variable if you like.)

$ export VM=sylabs/singularity-3.2-ubuntu-bionic64 && \
    vagrant init $VM && \
    vagrant up && \
    vagrant ssh

You can check the installed version of Singularity with the following:

vagrant@vagrant:~$ singularity version
3.2.0-1

Of course, you can also start with a plain OS Vagrant box as a base and then install Singularity using one of the above methods for Linux.

Singularity on a shared resource

Perhaps you are a user who wants a few talking points and background to share with your administrator. Or maybe you are an administrator who needs to decide whether to install Singularity.

This document, and the accompanying administrator documentation provides answers to many common questions.

If you need to request an installation you may decide to draft a message similar to this:

Dear shared resource administrator,

We are interested in having Singularity (https://www.sylabs.io/docs/)
installed on our shared resource. Singularity containers will allow us to
build encapsulated environments, meaning that our work is reproducible and
we are empowered to choose all dependencies including libraries, operating
system, and custom software. Singularity is already in use on many of the
top HPC centers around the world. Examples include:

    Texas Advanced Computing Center
    GSI Helmholtz Center for Heavy Ion Research
    Oak Ridge Leadership Computing Facility
    Purdue University
    National Institutes of Health HPC
    UFIT Research Computing at the University of Florida
    San Diego Supercomputing Center
    Lawrence Berkeley National Laboratory
    University of Chicago
    McGill HPC Centre/Calcul Québec
    Barcelona Supercomputing Center
    Sandia National Lab
    Argonne National Lab

Importantly, it has a vibrant team of developers, scientists, and HPC
administrators that invest heavily in the security and development of the
software, and are quick to respond to the needs of the community. To help
learn more about Singularity, I thought these items might be of interest:

    - Security: A discussion of security concerns is discussed at
    https://www.sylabs.io/guides/2.5.2/user-guide/introduction.html#security-and-privilege-escalation

    - Installation:
    https://www.sylabs.io/guides/3.2/user-guide/installation.html

If you have questions about any of the above, you can email the open source
list (singularity@lbl.gov), join the open source slack channel
(singularity-container.slack.com), or contact the organization that supports
Singularity directly to get a human response (sylabs.io/contact). I can do
my best to facilitate this interaction if help is needed.

Thank you kindly for considering this request!

Best,

User

As is stated in the sample message above, you can always reach out to us for additional questions or support.