Singularity is a technology to run software containers (think Docker containers) in an High-Performance Computing environment. The most striking difference in comparison to Docker is that running these singularity containers do not need root rights. However, creating or modifying these singularity images does need root rights.
Singularity is a software system that is in development. SURFsara aims to keep the version of singularity on our systems at the latest stable release. To keep our documentation up to date we decided to give some guidelines and do not provide in-depth generic information, but there are links to find this information. We guarantee no backward compatibility when singularity is upgraded.
Taken from the official website: http://singularity.lbl.gov
Singularity enables users to have full control of their environment. This means that a non-privileged user can “swap out” the operating system on the host for one they control. So if the host system is running RHEL6 but your application runs in Ubuntu, you can create an Ubuntu image, install your applications into that image, copy the image to another host, and run your application on that host in it’s native Ubuntu environment!
Before you can create your image you need to install singularity on a system where you have root rights. This can be done for example on your own machine, or on a virtual environment, either at your local computer, at SURFsara HPC Cloud, or at another Cloud resource provider. The root rights are necessary to create an image and to install the software on this machine.
When using a Redhat based system (CentOS, Fedora etc.), please install the Development Tools meta-package:
sudo yum groupinstall "Development Tools"
When using a Debian based system (Ubuntu, Kubuntu etc.), please install the Development Tools meta package:
sudo apt install build-essential gitTo install the same version as available on SURFsara systems do the following:
VERSION=2.4.2
wget https://github.com/singularityware/singularity/releases/download/$VERSION/singularity-$VERSION.tar.gz
tar xvf singularity-$VERSION.tar.gz
cd singularity-$VERSION/
./configure --prefix=/usr/local
make
sudo make install
To verify singularity is installed run:
singularity selftest
This is the preferred method of building and installing packages on a system. Files are managed by the package manager, which allows for easier removal and upgrading of packages.
VERSION=2.4.2
wget https://github.com/singularityware/singularity/releases/download/$VERSION/singularity-$VERSION.tar.gz
tar --no-same-owner -xvf singularity-$VERSION.tar.gz
mkdir -p ~/rpmbuild/{BUILD,RPMS,SOURCES,SPECS,SRPMS}
mv singularity-$VERSION.tar.gz ~/rpmbuild/SOURCES/
mv singularity-$VERSION/singularity.spec ~/rpmbuild/SPECS/
rpmbuild -ba ~/rpmbuild/SPECS/singularity.spec
sudo yum install ~/rpmbuild/RPMS/*/singularity-[0-9]*.rpm
To verify singularity is installed run
singularity selftestA good starting point is finding suitable containers is Docker Hub.
You can find for example the latest Ubuntu container at https://hub.docker.com/_/ubuntu/. To get the image use the pull command
sudo singularity pull docker://ubuntu:latest
Take a look around in the container start a shell with:
singularity shell --pwd $PWD ubuntu-latest.simg
By default, the /home directory will be bound to your image. Changes made inside the image to the files that are bound also take effect outside the container. Deleting, creation and modification of files in your images home directory removes also the files from the host.
Changes inside the image made to the image itself (not to the directories that are bound) will not be saved and you will not have root rights inside the container. To make permanent adjustments continue at post hoc adjustments.
How to create a image from scratch can be found at http://singularity.lbl.gov/quickstart#singularity-recipes
Current local Docker images can be shown with sudo docker images where you can find the ID or IMAGE ID
$ sudo docker images
Password:
REPOSITORY TAG IMAGE ID CREATED SIZE
tensorflow/tensorflow latest 0bb45d441a4b 6 days ago 1.15 GB
singularityware/docker2singularity latest 9a621f249838 3 weeks ago 101 MB
asciinema2gif latest 386c8b5977de 3 weeks ago 56.2 MB
To convert the image you need to set up a local Docker registry
sudo docker run -d -p 5000:5000 --name registry registry:2
tag the wanted images and push it to the registry
sudo docker image tag tensorflow/tensorflow localhost:5000/mytensorflow
sudo docker push localhost:5000/mytensorflow
Now you can use singularity to pull the images from your private local registry. The registry has no encryption and we must tell singularity to ignore lack of https with the prefix "SINGULARITY_NOHTTPS=true"
sudo SINGULARITY_NOHTTPS=true singularity build mytenserflow.img docker://localhost:5000/mytensorflow
Stop the docker registry and clean up
sudo docker container stop registry && docker container rm -v registry
When you need to install additional software or change some settings you can execute commands using shell commands inside the image. Keep in mind that you will need root permissions for these operations.
First step is to convert the compressed image into a uncompressed format in a folder structure (called a sandbox)
sudo singularity build --sandbox sandbox ubuntu-latest.simgTo keep the image persistent use the --writeable option. e.g.
sudo singularity shell --writable sandbox/
Exiting the image can be done by exiting the shell with the exit command.
After editing you compress the sandbox to ensure portability and ease of use with
sudo singularity build myubuntu.simg sandbox/
To ensure you can reach data in scratch on NIKHEF systems while working on the grid you need to create a directory with the same name inside your image. This is also done with the following one-liner:
sudo singularity exec --writable example.img mkdir -p /tmpdir /cvmfs
After bootstrap has been completed on your system and tests have been done locally it is time to move the image to one of the SURFsara systems. The various systems have different best practices on where to put your image.
From your local system, you can do a SCP to Cartesius, with the following command the image will be placed in your home directory.
scp example.img username@cartesius.surfsara.nl:~/Or while using the Grid distribute it via Softdrive (cvmfs):
scp example.img softdrive.grid.sara.nl:/cvmfs/softdrive.nl/<username>/.and publish with
ssh softdrive.grid.sara.nl publish-my-softdriveFrom your local system you can do a scp to LISA with the following command the image will be placed in your home directory.
scp example.img username@lisa.surfsara.nl:~/.First create a directory on the scratch-shared part of the scratch file system ( NOTE: ofcourse there are a lot of other ways to use your image, we just give one example ).
SCRATCH_SHARED_DIR=$(mktemp -d -p /scratch-shared)Copy the image to the newly created scratch shared directory.
cp /place/where/you/store/image.img ${SCRATCH_SHARED_DIR}Go into the newly created directory
cd ${SCRATCH_SHARED_DIR}Start an interactive container sesion.
singularity shell --pwd $PWD ${SCRATCH_SHARED_DIR}/test.imgJump into the scratch directory
cd $TMPDIRcopy your image to the scratch space
cp ~/example.img .
singularity exec --pwd $PWD example.img echo "hello world"When you start a job you start by default in the scratch dir ($TMPDIR) and there is no need to switch to another directory. Images are automaticly cached by the cvmfs filesystem and there is no need to copy them to the scratch ($TMPDIR)
singularity exec --pwd $PWD /cvmfs/softdrive.nl/<username>/example.img echo "hello world"$PATH variable?The $PATH variable is taken from host environment. You can add a path to $PATH with
export PATH=/test/:$PATH
sudo singularity exec example.img echo $PATHTo make the PATH persistent in your image, add the export PATH line to "/environment" inside the container
This is most likely caused by the software that was needed to build the software. Think of compilers, development headers and source code.
To make the image smaller you can best uninstall these packages and source code compress the package. Hereby an example which works on a ubuntu based container.
Before we can edit the image we need to convert it to an editable sandbox format
sudo singularity build --sandbox sandbox ubuntu-latest.simg Then bash inside your sandbox with sudo rights:
sudo singularity shell --writable sandbox To detect the largest packages we run the following one-liner which prints package size and sort them by size (from small to big)
dpkg-query -W --showformat='${Installed-Size;10}\t${Package}\n' | sort -k1,1nThen we select the big package, which are not needed at runtime. This depends on your software stack but in general, it is save to remove gcc, clang, and *-dev packages.
For instance:
sudo apt remove gcc *-devAlso, remove the unneeded old packages and removing the cache of apt might help to clean the container.
sudo apt autoremove
sudo apt cleanAfter cleaning the container can converted back to a compressed format with
sudo singularity build myubuntu-small.simg sandbox/ --pwd $PWD option necessary?By default, Singularity makes the current working directory in the container the same as on the host. For resolving the current working directory, Singularity looks up the physical absolute path (see man pwd for more info). However, many directories on our systems are symbolic links and the current working directory would resolve different than expected. This results that your files are not were you expected them to be (combined with some warning messages).
Yes, there is! You can write a Singularity bootstrap file (or convert Dockerfile to Singularity bootstrap ). However, this is not as well documented as the Docker ecosphere.
A singularity bootstrap file is a recipe to create a singularity image(or Singularities counterpart of a Dockerfile )
Information about writing a Singularity bootstrap file can be found at http://singularity.lbl.gov/bootstrap-image.
An easy tool to convert a from Dockerfile can be found at singularity-hub.org
The SURFsara Data Archive allows the user to safely archive up to petabytes of valuable research data.
Persistent identifiers (PIDs) ensure the findability of your data. SURFsara offers a PID provisioning service in cooperation with the European Persistent Identifier Consortium (EPIC).
B2SAFE is a robust, secure and accessible data management service. It allows common repositories to reliably implement data management policies, even in multiple administrative domains.
The Data Ingest Service is a service provided by SURFsara for users that want to upload a large amount of data to SURFsara and who not have the sufficient amount...
The Collaboratorium is a visualization and presentation space for science and industry. The facility is of great use for researchers that are faced with...
Data visualization can play an important role in research, specifically in data analysis to complement other analysis methods, such as statistical analysis.