Singularity is a container solution for computing: Singularity Website. Linux containers allow to encapsulate code within environment (librairies, compilers, etc.) in a portable image.

Previous tutorials:

Other documents:

Note on Singularity version:

  • 2.6.1: December 2018 ⇒ LTS;

  • 3.0.1: November 2018, new implementation of Singularity;

  • 3.4.1: September 2019;

  • 3.5.0: November 2019.

Singularity v3.4.1 will be used in this tutorial!

Singularity has to be used in three steps:

  • build a Singularity image from a Singularity file locally or from the GitLab-CI as root user;

  • push the Singularity image on a Hub or a Registry;

  • execute a Singularity image on a computing cluster as normal user: APC cluster and CC-IN2P3 batch system.

Singularity v3

  • in C and Go;

  • new format of images (SIF): ability to sign and verify containers;

  • work with private GitLab Registry but don’t support the Singularity Hub;

  • better integration with Docker containers: ORAS registry standard;

  • Singularity Desktop for macOS (Beta v0.1 release).

  • Support for AMD gpus

Use Singularity

Locally with the Singularity client

Linux users

CentOs
$ sudo yum update -y && \
    sudo yum install -y epel-release && \
    sudo yum update -y && \
    sudo yum install -y singularity-runtime singularity
Ubuntu Xenial
$ sudo apt install golang
$ export VERSION=3.5.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
$ ./mconfig && \
    make -C builddir && \
    sudo make -C builddir install
$ singularity --version

Mac users

For Mac users, a new tool is available: Singularity Desktop for macOS.

  • Native usage:

$ singularity --version
singularity version 3.3.0-rc.1.658.g7427b73f1.dirty

  • Configuration files:

$ .singularity/cache/ => images
$ .singularity/remote.yaml => Sylabs cloud configuration

  • Limitations:

    • less commands (inspect…​);

    • non local build: Sylabs cloud (see below);

$ singularity build --remote centos.sif docker://centos

  • mounting: different name for host and container.

$ singularity exec -B /tmp -B /var/tmp docker://centos

Manage SIF images

Singularity Hub (SHub) is no longer supported, we will see if we keep our private Shub (sregistry.in2p3.fr).

Search

$ singularity search centos
Found 20 containers for 'centos'
        library://library/default/centos
                Tags: 6 7 7.6 7.6.1810 latest
$ singularity pull library://library/default/centos:7
$ singularity verify centos_7.sif
$ singularity inspect centos_7.sif
==labels==
org.label-schema.usage.singularity.deffile.bootstrap: yum
...

Pull

$ singularity pull library://library/default/centos:7
$ singularity pull docker://centos:7
$ singularity pull shub://sregistry.in2p3.fr/apc/tp-singu:latest
$ singularity pull image.sif oras://gitlab-registry.in2p3.fr/user/project:tag

Run/exec/shell

$ singularity run library://godlovedc/funny/lolcow
$ singularity exec docker://centos ls
$ singularity shell centos.sif

Recipe

By default Singularity bind mounts /home/$USER, /tmp, and $PWD into your container at runtime.
Definition file
BootStrap: library
From: ubuntu:16.04
%post
    apt-get -y update
    apt-get -y install fortune cowsay lolcat
%environment
    export LC_ALL=C
    export PATH=/usr/games:$PATH
%runscript
    fortune | cowsay | lolcat
%labels
    Author GodloveD
BootStrap

  • library (images hosted on the Container Library ⇒ Sylabs cloud);

  • docker (images hosted on Docker Hub);

  • shub (images hosted on Singularity Hub);

From: shub://<registry>/<username>/<container-name>:<tag>@digest

  • local image (images saved on your machine);

From: /path/to/container/file/or/directory

  • yum (yum based systems such as CentOS).

Bootstrap: yum
OSVersion: 7
MirrorURL: http://mirror.centos.org/centos-%{OSVERSION}/%{OSVERSION}/os/$basearch/
Include: yum

Build and share images

Local build

Build
$ singularity build app.sif app.def

  • Sanbox: create a directory with all the image content.

$ singularity build --sandbox ubuntu/ library://ubuntu

Sylabs cloud

Build
$ singularity remote login
$ singularity build --remote centos.sif docker://centos
$ ls centos.sif
$ singularity pull library://user/remote-builds/id
Push
$ singularity sign image.sif
$ singularity push image.sif library://user/default/lisa:1.0
Pull
$ singularity pull library://user/default/lisa

GitLab CI

Use Docker images from GitLab private registries

Docker registry login methods

  • interactive password:

$ singularity pull docker://private_registry

  • prompted password:

$ singularity pull --docker-username user --docker-password password docker://private_registry

  • prompted password with environnement variables:

$ export SINGULARITY_DOCKER_USERNAME=username
$ export SINGULARITY_DOCKER_PASSWORD=password
$ singularity pull docker://private_registry

  • JSON file:

$ cat ~/.docker/config.json
DOCKER_TOKEN

  • deploy token:

$ export SINGULARITY_DOCKER_USERNAME=gitlab+deploy-token-id
$ export SINGULARITY_DOCKER_PASSWORD=token
$ singularity pull docker://gitlab-registry.in2p3.fr/stas/mldc:43-update-convention-for-polarisation-inclination

Methodology on GitLab CI

  • Private project token:

    • in your private project (such as LDC), create a deploy token (settings/repo/deploy token) with read_registry wright;

  • Private registries usage:

    • in your new project, put two environnement variables in variables (settings/ci/cd/variables) such as SINGULARITY_DOCKER_USERNAME and SINGULARITY_DOCKER_PASSWORD;

    • in your Singularity file, directly use the Docker image from a private project;

Definition file
Bootstrap: docker
From: gitlab-registry.in2p3.fr/stas/mldc:43-update-convention-for-polarisation-inclination
%post
  ...

  • in your .gitlab-ci.yaml, build directly the Singularity image.

gitlab-ci.yaml
singularity:
  stage: build
  image:
    name: quay.io/singularity/singularity:v3.4.0
    entrypoint: [""]
  script:
    - singularity build app.sif app.def

  • In case of several deploy token:

gitlab-ci.yaml
singularity:
  stage: build
  image:
    name: quay.io/singularity/singularity:v3.4.0
    entrypoint: [""]
script:
    - singularity build --docker-username $SINGULARITY_DOCKER_USERNAME_LDC --docker-password $SINGULARITY_DOCKER_PASSWORD app.sif app.def

Rebuild dependance images

  • Build a new mother image at each commit: connect a workflow with another.

  • WIP…​

Push Singularity image on a shareable place

Singularity hub
Docker Registry

  • To push and pull Singularity images in a Docker Registry:

Push
$ singularity push --docker-username user --docker-password passwd app.sif oras://gitlab-registry.in2p3.fr/user/project:latest
Pull
$ singularity pull --docker-username user --docker-password passwd app.sif oras://gitlab-registry.in2p3.fr/user/project:latest

  • To use it in GitLab-CI:

gitlab-ci.yaml
singularity:
  stage: deploy
  image:
    name: quay.io/singularity/singularity:v3.4.0
    entrypoint: [""]
  script:
    - singularity build ...
    #- singularity push --docker-username "${CI_REGISTRY_USER}" --docker-password "${CI_REGISTRY_PASSWORD}" app.sif oras://"$CI_REGISTRY_IMAGE"/"$CI_PROJECT_NAME":"$CI_COMMIT_TAG"
    - singularity push --docker-username "${CI_REGISTRY_USER}" --docker-password "${CI_REGISTRY_PASSWORD}" app.sif oras://"$CI_REGISTRY_IMAGE":"$CI_COMMIT_REF_NAME"

Use Singularity on VM, APC cluster and CC-IN2P3

Both versions 2.6 and 3.4 are available on the different systems.

VM 74.72

$ export SINGULARITY_TMPDIR=/data/tmp => change tmpdir
$ singularity --version
2.6.1-dist
$ singularity_v3
singularity version 3.4.0-1

APC cluster

$ singularity --version
singularity version 3.4.2-1.1.osg34.el7
$ /soft/singularity/bin/singularity --version
2.6.1-dist

CC-IN2P3

$ singularity --version
2.6.1-dist
$ ccenv --list singularity
$ ccenv singularity 3.4.2