Quickstart

Install Sarus

You can quickly install Sarus by following the simple steps below.

  1. Download the latest standalone Sarus archive from the official GitHub Releases:

    mkdir /opt/sarus
    cd /opt/sarus
    # Adjust url to your preferred version
    wget https://github.com/eth-cscs/sarus/releases/download/1.0.1/sarus-Release.tar.gz
    
  2. Extract Sarus in the installation directory:

    cd /opt/sarus
    tar xf sarus-Release.tar.gz
    
  3. Run the configuration script to finalize the installation of Sarus:

    cd /opt/sarus/1.0.1-Release  # adapt folder name to actual version of Sarus
    sudo ./configure_installation.sh
    

    Important

    The configuration script needs to run with root privileges in order to set Sarus as a root-owned SUID program.

    The configuration script requires the program mksquashfs to be installed on the system, which is typically available through the squashfs-tools package.

    Also note that the configuration script will create a minimal working configuration. For enabling additional features, please refer to the Configuration file reference.

    Note

    You can refer to the section Custom installation if you want to build Sarus from source or from the Spack package manager.

    Important

    As explained by the output of the previous script, you need to persistently add Sarus to your PATH. I.e., something like adding “export PATH=/opt/sarus/bin:${PATH}” to your .bashrc.

  4. Perform the Post-installation actions.

    Note

    The Sarus binary from the standalone archive looks for SSL certificates into the /etc/ssl directory. Depending on the Linux distribution, some certificates may be located in different directories. A possible solution to expose the certificates to Sarus is a symlink. For example, on CentOS 7 and Fedora 31:

    sudo ln -s /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem /etc/ssl/cert.pem
    

Use Sarus

Now Sarus is ready to be used. Below is a list of the available commands:

help: Print help message about a command
images: List images
load: Load the contents of a tarball to create a filesystem image
pull: Pull an image from a registry
rmi: Remove an image
run: Run a command in a new container
ssh-keygen: Generate the SSH keys in the local repository
version: Show the Sarus version information

Below is an example of some basic usage of Sarus:

$ sarus pull alpine
# image            : index.docker.io/library/alpine/latest
# cache directory  : "/home/user/.sarus/cache"
# temp directory   : "/tmp"
# images directory : "/home/user/.sarus/images"
> save image layers ...
> pulling        : sha256:9d48c3bd43c520dc2784e868a780e976b207cbf493eaff8c6596eb871cbd9609
> completed      : sha256:9d48c3bd43c520dc2784e868a780e976b207cbf493eaff8c6596eb871cbd9609
> expanding image layers ...
> extracting     : "/home/user/.sarus/cache/sha256:9d48c3bd43c520dc2784e868a780e976b207cbf493eaff8c6596eb871cbd9609.tar"
> make squashfs image: "/home/user/.sarus/images/index.docker.io/library/alpine/latest.squashfs"

$ sarus images
REPOSITORY   TAG          DIGEST         CREATED               SIZE         SERVER
alpine       latest       65e50dd72f89   2019-08-21T16:07:06   2.59MB       index.docker.io

$ sarus run alpine cat /etc/os-release
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.10.2
PRETTY_NAME="Alpine Linux v3.10"
HOME_URL="https://alpinelinux.org/"
BUG_REPORT_URL="https://bugs.alpinelinux.org/"

Note

You can refer to the section User guides for more information on how to use Sarus.