Installation¶
This document will guide you through the process of installing Singularity >= 3.0.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 (>=v3.0.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 \
pkg-config
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¶
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.11 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
If you are installing Singularity v3.0.0 you will also need to install dep
for dependency resolution.
$ go get -u github.com/golang/dep/cmd/dep
Install from source¶
The following commands will install Singularity from the GitHub repo to /usr/local. This method will
work for >=v3.0.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.0 with the latest bug fixes and enhancements checkout
release-3.0. Release branches may be less stable than code in a tagged point release.master branch: The
masterbranch 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. Themasterbranch changes quickly and may be unstable.
Download Singularity repo (and optionally check out a tag or branch)¶
To ensure that the Singularity source code is downloaded to the appropriate directory use these commands.
$ go get -d github.com/sylabs/singularity
Go will complain that there are no Go files, but it will still download the
Singularity source code to the appropriate directory within the $GOPATH.
Now checkout the version of Singularity you want to install.
$ export VERSION=v3.0.3 # or another tag or branch if you like && \
cd $GOPATH/src/github.com/sylabs/singularity && \
git fetch && \
git checkout $VERSION # omit this command to install the latest bleeding edge code from master
Download and install Singularity from a release¶
You can also install Singularity from one of our releases. For this, you can simply download a release from <https://github.com/sylabs/singularity/releases>`_. After that you can just run the following commands to proceed with the installation.
Note
Make sure to update the release version before running the following commands.
$ export VERSION=3.0.3 && # adjust this as necessary \
mkdir -p $GOPATH/src/github.com/sylabs && \
cd $GOPATH/src/github.com/sylabs && \
wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-${VERSION}.tar.gz && \
tar -xzf singularity-${VERSION}.tar.gz && \
cd ./singularity && \
./mconfig
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 thesingularity.conffile 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--localstatedirshould 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 download the tarball and build and install the RPM.
$ export VERSION=3.0.3 && # 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
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¶
When you run sudo make install, the command lists files as they are
installed. They must all be removed in order to completely remove Singularity.
For example, in a standard installation of Singularity 3.0.1 (when building from source) 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:
Mac¶
You need to install several programs. This example uses Homebrew but you can also install these tools using the GUI.
First, optionally install Homebrew.
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Next, install Vagrant and the necessary bits (either using this method or by downloading and installing the tools manually).
$ brew cask install virtualbox && \
brew cask install vagrant && \
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.0-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.0.3-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.