.. highlight:: sh

Racker

.. container::

*Operating system containers for humans and machines.*

- **Documentation**: https://github.com/cicerops/racker
- **Source code**: https://github.com/cicerops/racker
- **PyPI**: https://pypi.org/project/racker/

|

.. image:: https://img.shields.io/badge/systemd-239%20and%20newer-blue.svg :target: https://github.com/systemd/systemd :alt: systemd System and Service Manager

.. image:: https://img.shields.io/pypi/pyversions/racker.svg :target: https://pypi.org/project/racker/ :alt: Python version

.. image:: https://img.shields.io/pypi/v/racker.svg :target: https://pypi.org/project/racker/ :alt: Version

.. image:: https://img.shields.io/pypi/status/racker.svg :target: https://pypi.org/project/racker/ :alt: Maturity status

.. image:: https://github.com/cicerops/racker/workflows/Tests/badge.svg :target: https://github.com/cicerops/racker/actions?workflow=Tests :alt: Test suite status

.. image:: https://codecov.io/gh/cicerops/racker/branch/main/graph/badge.svg :target: https://codecov.io/gh/cicerops/racker :alt: Test suite code coverage

.. image:: https://img.shields.io/pypi/l/racker.svg :target: https://pypi.org/project/racker/ :alt: License

.. image:: https://pepy.tech/badge/racker/month :target: https://pepy.tech/project/racker :alt: PyPI downloads / month

---

---

About

---

Introduction

Racker is an experimental harness tool for provisioning and launching containers, with a focus on operating system containers <OS containers_>_.

By a "harness tool", we mean a combination of image bakery and payload launcher.

• The image bakery is based on modern and generic tools for creating machine images like mkosi_ and Packer, as well OCI-compliant container images <OCI Image Format_>. Container images can be acquired from both vendor- specific and standardized distribution channels like OCI-compliant image registries <OCI Distribution Specification_>_.
• A payload is any of an interactive command prompt (shell), a single program invocation, or a long-running daemon.

Details

Racker is ...

• A lightweight wrapper around systemd-nspawn to provide and launch container environments for/with systemd.

• A lightweight wrapper around vagrant to provide convenient access to all things needing a full VM, like running Windows on Linux or macOS.

• A tribute to the authors and contributors of GNU, Linux, systemd, Python, VirtualBox, Vagrant, Docker, Windows, Windows Docker Machine and countless others.

With Racker, you can ...

• Launch interactive command prompts or invoke programs non-interactively within a isolated and volatile Linux and Windows environments.

• Build upon the runtime harness framework to build solutions for running and testing software packages in different environments, mostly run headless and non-interactively.

Runner backends

Racker has two different subsystems / runner backends, one for Linux and another one for Windows.

• For running Linux operating system containers, Racker uses systemd_ and systemd-nspawn_. Provisioning of additional software is performed using the native package manager of the corresponding Linux distribution.

Operating system coverage

On the host side, Racker can run on Linux, macOS, and Windows. On the container side, the following list of operating systems has been verified to work well.

Linux .....

• AmazonLinux 2022
• Arch Linux 20220501
• CentOS 7-9
• Debian 9-12 and unstable (stretch, buster, bullseye, bookworm, sid)
• Fedora 35-37
• openSUSE 15 and latest (leap, tumbleweed)
• Oracle Linux 8
• Red Hat RHEL 8 and 9
• Rocky Linux 8
• SUSE SLES 15 and BCI:latest
• Ubuntu LTS 20 and 22 (focal, jammy)

Prior art

The aims of Racker are very similar to Docker, Podman, Distrobox_ and Toolbox_. However, there are also some differences.

Most people running Linux probably want to use Podman_ these days. For more background, enjoy reading Container wars_ and Container Tools Guide_.

• Racker is currently based on systemd-nspawn_ and Vagrant_ instead of Docker_ or Podman_.
• Racker's focus is to provide easy provisioning and launching OS containers_ aka. OS-level virtualization, using systemd as init process.
• The acquisition and provisioning of operating system images does not need any special preparation steps, those are handled by Racker on the fly.
• Racker aims to provide concise usability by folding its usage into a single command.
• Racker is written in Python instead of Golang or Bash.

See also Comparison with similar tools - more details_.

About systemd-nspawn

``systemd-nspawn`` may be used to run a command or OS in a light-weight
namespace container. In many ways it is similar to ``chroot``, but more
powerful since it fully virtualizes the file system hierarchy, as well as
the process tree, the various IPC subsystems and the host and domain name.

It is primarily intended for use in development, experimenting, debugging,
instrumentation, testing and building of software.

It can easily be used to start containers capable of booting up a complete
and unmodified Linux distribution inside as normal system services.

For learning more details about systemd-nspawn, we strongly recommend to read the more extensive systemd-nspawn in a nutshell_.

---

Setup

---

Install prerequisites::

apt-get update
apt-get install --yes systemd-container skopeo umoci python3-pip python3-venv

Install Racker::

python3 -m venv .venv
source .venv/bin/activate
pip install racker --upgrade

To install the latest development version, use this command instead::

pip install git+https://github.com/cicerops/racker --upgrade

.. note::

If you are not running Linux on your workstation, the documentation about
the `Racker sandbox installation`_ outlines how to run this program within
a virtual machine using Vagrant.

---

Usage

---

Racker

The racker program aims to resemble the semantics of Docker by providing a command line interface compatible with the docker command.

::

# Invoke the vanilla Docker `hello-world` image.
# FIXME: Does not work yet.
# racker run -it --rm hello-world /hello
# racker run -it --rm quay.io/podman/hello

# Acquire rootfs images.
racker pull debian:bullseye-slim
racker pull fedora:37

# Launch an interactive shell.
racker run -it --rm debian:bullseye-slim bash
racker run -it --rm fedora:37 bash
racker run -it --rm docker://registry.access.redhat.com/ubi8/ubi-minimal /bin/bash
racker run -it --rm docker://quay.io/centos/centos:stream9 bash

# Launch a single command.
racker run -it --rm debian:11-slim hostnamectl
racker run -it --rm opensuse/tumbleweed hostnamectl
racker run -it --rm ubuntu:jammy /bin/cat /etc/os-release
racker run -it --rm registry.suse.com/suse/sle15 /bin/cat /etc/os-release
racker run -it --rm registry.suse.com/bci/bci-base:15.4 /bin/cat /etc/os-release
racker run -it --rm docker://ghcr.io/jpmens/mqttwarn-standard /usr/bin/hostnamectl

# Verbose mode.
racker --verbose run -it --rm fedora:37 hostnamectl

# Use stdin and stdout, with timing.
time echo "hello world" | racker run -it --rm fedora:37 cat /dev/stdin > hello
cat hello

Postroj

The idea behind postroj is to provide an entrypoint to a command line interface implementing actions that don't fit into racker, mostly having a more high-level character.

Currently, postroj pkgprobe implements a flavor of full system integration/acceptance testing in order to test the soundness of actual installed binary distribution packages, in the spirit of autopkgtest_.

To do so, it implements the concept of curated operating system images, whose labels have a different layout than labels of Docker filesystem images.

Getting started::

# List available images.
postroj list-images

# Acquire images for curated operating systems.
postroj pull debian-bullseye
postroj pull fedora-37

# Acquire rootfs images for all available distributions.
postroj pull --all

# Run a self test procedure, invoking `hostnamectl` on all containers.
postroj selftest hostnamectl

Package testing::

# Run a self test procedure, invoking example probes on all containers.
postroj selftest pkgprobe

# Run two basic probes on different operating systems.
postroj pkgprobe --image=debian-bullseye --check-unit=systemd-journald
postroj pkgprobe --image=fedora-37 --check-unit=systemd-journald
postroj pkgprobe --image=archlinux-20220501 --check-unit=systemd-journald

# Run probes that need to install a 3rd party package beforehand.

postroj pkgprobe \
    --image=debian-stretch \
    --package=http://ftp.debian.org/debian/pool/main/w/webfs/webfs_1.21+ds1-12_amd64.deb \
    --check-unit=webfs \
    --check-network=http://localhost:8000

postroj pkgprobe \
    --image=debian-bullseye \
    --package=https://dl.grafana.com/oss/release/grafana_8.5.1_amd64.deb \
    --check-unit=grafana-server \
    --check-network=http://localhost:3000

postroj pkgprobe \
    --image=centos-8 \
    --package=https://dl.grafana.com/oss/release/grafana-8.5.1-1.x86_64.rpm \
    --check-unit=grafana-server \
    --check-network=http://localhost:3000

---

Performance

---

A SuT which just uses a dummy probe /bin/systemctl is-active systemd-journald on Debian 10 "buster" cycles quite fast, essentially demonstrating that the overhead of environment setup/teardown is insignificant.

::

time postroj pkgprobe --image=