About Singularity

What is Singularity?

Singularity is a tool to run software inside containers, similar to Docker. Compared to Docker it has a higher focus on security and can be used without root permission. Also programs in the container are executed as the user of the host system which makes it much more convenient when touching files of the host system (as it is happening when building a mounted workspace).

Get our Singularity Image

We provide a Singularity image with Ubuntu 20.04 with all dependencies needed to build and run the software here. You can download the latest version using:

singularity pull library://felix.widmaier/trifinger/base:latest

Install Singularity

We are using Singularity version 3.7. Other recent versions are probably also so fine, however, we cannot guarantee compatibility for those. Unfortunately, most versions of Ubuntu still provide Singularity version 2.x in their official repositories. A newer version can be installed from source in this case. For this you may follow the official installation instructions or use the following, slightly simplified instructions (assuming you are working with Ubuntu).

Install system dependencies:

$ 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

Get the required version of the Go compiler:

cd ~/Downloads  # you can save it anywhere else, just adjust paths below
wget https://dl.google.com/go/go1.13.linux-amd64.tar.gz
tar -xzf go1.13.linux-amd64.tar.gz

Note that it is only needed once for building singularity, so no need to install it permanently (we just add it to PATH temporarily for building, see below).

Now download and unpack the singularity source:

wget https://github.com/sylabs/singularity/releases/download/v3.7.1/singularity-3.7.1.tar.gz
tar -xzf singularity-3.7.1.tar.gz

And finally build and install it:

export PATH=~/Downloads/go/bin:${PATH}  # adjust path if you used a different directory
cd singularity  # the folder to which the singularity source was extracted
./mconfig
cd builddir
make
sudo make install

Now you should be able to use Singularity. You can test this, for example, by running singularity –version which should print “singularity version 3.7.1”. For more information on how to use Singularity, see the official documentation.

Run Something in the Container

To run the container in shell mode (i.e. opening a shell inside the container), the following is often enough:

singularity shell path/to/image.sif

This will, however, be influenced by your local setup as environment variables are exported and the home directory is mounted by default. Further the current working directory from which singularity is run is also bound inside the container.

This default behaviour is often convenient but can cause issues in some cases. A typical example would be a Python package installed in your home directory (which will then be available in the container) which is not compatible with versions of other packages inside the container. To avoid these kind of issues it is recommended to use the following command to run the container in a more isolated way:

export SINGULARITYENV_DISPLAY=$DISPLAY
singularity shell -e --no-home -B $(pwd) path/to/image.sif

The arguments explained:

  • The first line makes sure the DISPLAY environment variable is set correctly inside the container (only needed if you want to run GUI-based applications).

  • -e (short for --cleanenv) prevents environment variables to be exported.

  • --no-home prevents your home directory from being bound.

  • -B $(pwd) explicitly binds the current working directory. This is needed if the working directory is inside your home directory as otherwise it is excluded by the --no-home.

Note that with the above the current working directory is still bound in the image, so it is possible to build/modify the workspace from the host-system when Singularity is run from the root directory of the workspace.

Compatibility with Nvidia Drivers

When you are using Nvidia drivers and want to run a GUI-based application in the container, you may need to add the --nv flag:

singularity shell --nv ... path/to/image.sif

Add Custom Dependencies to the Container

The image we provide already includes everything needed to run the robot and the simulation. However, you may need additional libraries to use them in our own code, which are not yet present. In this case, you can create your own image which is based on our standard image but extends it with your additional dependencies.

To extend the image, create definition file like the following:

# Specify the name of the base image below
Bootstrap: localimage
From: ./base_image.sif

%post
    # Put commands to install additional dependencies here.
    # Make sure everything runs automatically without human input (e.g. add
    # `-y` to automatically say "yes" below).
    apt-get install -y package_name

See the official Documentation for Definition Files for all options in the definition file.

Assuming you called your definition file user_image.def, use the following command to build the image. Note that the base image (specified in the From: line) needs to be present in the directory in which you call the command.

$ singularity build --fakeroot user_image.sif path/to/user_image.def