{"id":15478455,"url":"https://github.com/pyveci/racker","last_synced_at":"2026-03-17T22:06:50.792Z","repository":{"id":38289369,"uuid":"487960631","full_name":"pyveci/racker","owner":"pyveci","description":"Racker is an experimental harness tool for provisioning and running operating system containers.","archived":false,"fork":false,"pushed_at":"2025-11-24T11:44:34.000Z","size":277,"stargazers_count":6,"open_issues_count":13,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-02T15:18:07.362Z","etag":null,"topics":["docker","docker-image","harness","harness-framework","machinectl","oci","oci-image","oci-images","skopeo","systemd","systemd-container","systemd-nspawn","systemd-run","test-environment","test-harness","testing","testing-tool","umoci"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pyveci.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-05-02T19:08:14.000Z","updated_at":"2025-05-18T20:01:20.000Z","dependencies_parsed_at":"2022-09-13T13:02:32.929Z","dependency_job_id":"bc60c2fa-8289-4172-be9c-4ba542437155","html_url":"https://github.com/pyveci/racker","commit_stats":{"total_commits":134,"total_committers":2,"mean_commits":67.0,"dds":0.02985074626865669,"last_synced_commit":"2558046f1187bdff2810146b4a68bd43079626c8"},"previous_names":["pyveci/racker","cicerops/racker"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/pyveci/racker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyveci%2Fracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyveci%2Fracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyveci%2Fracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyveci%2Fracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pyveci","download_url":"https://codeload.github.com/pyveci/racker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pyveci%2Fracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30633240,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T17:32:55.572Z","status":"ssl_error","status_checked_at":"2026-03-17T17:32:38.732Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","docker-image","harness","harness-framework","machinectl","oci","oci-image","oci-images","skopeo","systemd","systemd-container","systemd-nspawn","systemd-run","test-environment","test-harness","testing","testing-tool","umoci"],"created_at":"2024-10-02T04:04:28.457Z","updated_at":"2026-03-17T22:06:50.771Z","avatar_url":"https://github.com/pyveci.png","language":"Python","readme":".. highlight:: sh\n\n\n######\nRacker\n######\n\n.. container::\n\n    *Operating system containers for humans and machines.*\n\n    - **Documentation**: https://github.com/cicerops/racker\n    - **Source code**: https://github.com/cicerops/racker\n    - **PyPI**: https://pypi.org/project/racker/\n\n|\n\n.. image:: https://img.shields.io/badge/systemd-239%20and%20newer-blue.svg\n    :target: https://github.com/systemd/systemd\n    :alt: systemd System and Service Manager\n\n.. image:: https://img.shields.io/pypi/pyversions/racker.svg\n    :target: https://pypi.org/project/racker/\n    :alt: Python version\n\n.. image:: https://img.shields.io/pypi/v/racker.svg\n    :target: https://pypi.org/project/racker/\n    :alt: Version\n\n.. image:: https://img.shields.io/pypi/status/racker.svg\n    :target: https://pypi.org/project/racker/\n    :alt: Maturity status\n\n.. image:: https://github.com/cicerops/racker/workflows/Tests/badge.svg\n    :target: https://github.com/cicerops/racker/actions?workflow=Tests\n    :alt: Test suite status\n\n.. image:: https://codecov.io/gh/cicerops/racker/branch/main/graph/badge.svg\n    :target: https://codecov.io/gh/cicerops/racker\n    :alt: Test suite code coverage\n\n.. image:: https://img.shields.io/pypi/l/racker.svg\n    :target: https://pypi.org/project/racker/\n    :alt: License\n\n.. image:: https://pepy.tech/badge/racker/month\n    :target: https://pepy.tech/project/racker\n    :alt: PyPI downloads / month\n\n\n----\n\n\n*****\nAbout\n*****\n\n\nIntroduction\n============\n\nRacker is an experimental harness tool for provisioning and launching\ncontainers, with a focus on `operating system containers \u003cOS containers_\u003e`_.\n\nBy a \"harness tool\", we mean a combination of image bakery and payload\nlauncher.\n\n- The image bakery is based on modern and generic tools for creating machine\n  images like `mkosi`_ and `Packer`_, as well `OCI-compliant container images\n  \u003cOCI Image Format_\u003e`_. Container images can be acquired from both vendor-\n  specific and standardized distribution channels like `OCI-compliant image\n  registries \u003cOCI Distribution Specification_\u003e`_.\n- A payload is any of an interactive command prompt (shell), a single program\n  invocation, or a long-running daemon.\n\n\nDetails\n=======\n\nRacker is ...\n-------------\n\n- A lightweight wrapper around ``systemd-nspawn`` to provide and launch\n  container environments for/with ``systemd``.\n\n- A lightweight wrapper around ``vagrant`` to provide convenient access to all\n  things needing a full VM, like running Windows on Linux or macOS.\n\n- A tribute to the authors and contributors of GNU, Linux, systemd, Python,\n  VirtualBox, Vagrant, Docker, Windows, Windows Docker Machine and countless\n  others.\n\n\nWith Racker, you can ...\n------------------------\n\n- Launch interactive command prompts or invoke programs non-interactively\n  within a isolated and volatile Linux and Windows environments.\n\n- Build upon the runtime harness framework to build solutions for running and\n  testing software packages in different environments, mostly run headless and\n  non-interactively.\n\n\nRunner backends\n---------------\n\nRacker has two different subsystems / runner backends, one for Linux and\nanother one for Windows.\n\n- For running Linux operating system containers, Racker uses `systemd`_ and\n  `systemd-nspawn`_. Provisioning of additional software is performed using the\n  native package manager of the corresponding Linux distribution.\n\n\nOperating system coverage\n-------------------------\n\nOn the host side, Racker can run on Linux, macOS, and Windows. On the container\nside, the following list of operating systems has been verified to work\nwell.\n\n\nLinux\n.....\n- AmazonLinux 2022\n- Arch Linux 20220501\n- CentOS 7-9\n- Debian 9-12 and unstable (stretch, buster, bullseye, bookworm, sid)\n- Fedora 35-37\n- openSUSE 15 and latest (leap, tumbleweed)\n- Oracle Linux 8\n- Red Hat RHEL 8 and 9\n- Rocky Linux 8\n- SUSE SLES 15 and BCI:latest\n- Ubuntu LTS 20 and 22 (focal, jammy)\n\n\nPrior art\n---------\n\nThe aims of Racker are very similar to `Docker`_, `Podman`_, `Distrobox`_ and\n`Toolbox`_. However, there are also some differences.\n\nMost people running Linux probably want to use `Podman`_ these days. For more\nbackground, enjoy reading `Container wars`_ and `Container Tools Guide`_.\n\n- Racker is currently based on `systemd-nspawn`_ and `Vagrant`_ instead of\n  `Docker`_ or `Podman`_.\n- Racker's focus is to provide easy provisioning and launching `OS containers`_\n  aka. `OS-level virtualization`_, using `systemd`_ as init process.\n- The acquisition and provisioning of operating system images does not need any\n  special preparation steps, those are handled by Racker on the fly.\n- Racker aims to provide concise usability by folding its usage into a single\n  command.\n- Racker is written in Python instead of Golang or Bash.\n\nSee also `Comparison with similar tools - more details`_.\n\n\nAbout ``systemd-nspawn``\n========================\n\n    ``systemd-nspawn`` may be used to run a command or OS in a light-weight\n    namespace container. In many ways it is similar to ``chroot``, but more\n    powerful since it fully virtualizes the file system hierarchy, as well as\n    the process tree, the various IPC subsystems and the host and domain name.\n\n    It is primarily intended for use in development, experimenting, debugging,\n    instrumentation, testing and building of software.\n\n    It can easily be used to start containers capable of booting up a complete\n    and unmodified Linux distribution inside as normal system services.\n\nFor learning more details about ``systemd-nspawn``, we strongly recommend to\nread the more extensive `systemd-nspawn in a nutshell`_.\n\n\n*****\nSetup\n*****\n\nInstall prerequisites::\n\n    apt-get update\n    apt-get install --yes systemd-container skopeo umoci python3-pip python3-venv\n\nInstall Racker::\n\n    python3 -m venv .venv\n    source .venv/bin/activate\n    pip install racker --upgrade\n\nTo install the latest development version, use this command instead::\n\n    pip install git+https://github.com/cicerops/racker --upgrade\n\n.. note::\n\n    If you are not running Linux on your workstation, the documentation about\n    the `Racker sandbox installation`_ outlines how to run this program within\n    a virtual machine using Vagrant.\n\n\n\n*****\nUsage\n*****\n\n\nRacker\n======\n\nThe ``racker`` program aims to resemble the semantics of Docker by providing a\ncommand line interface compatible with the ``docker`` command.\n\n::\n\n    # Invoke the vanilla Docker `hello-world` image.\n    # FIXME: Does not work yet.\n    # racker run -it --rm hello-world /hello\n    # racker run -it --rm quay.io/podman/hello\n\n    # Acquire rootfs images.\n    racker pull debian:bullseye-slim\n    racker pull fedora:37\n\n    # Launch an interactive shell.\n    racker run -it --rm debian:bullseye-slim bash\n    racker run -it --rm fedora:37 bash\n    racker run -it --rm docker://registry.access.redhat.com/ubi8/ubi-minimal /bin/bash\n    racker run -it --rm docker://quay.io/centos/centos:stream9 bash\n\n    # Launch a single command.\n    racker run -it --rm debian:11-slim hostnamectl\n    racker run -it --rm opensuse/tumbleweed hostnamectl\n    racker run -it --rm ubuntu:jammy /bin/cat /etc/os-release\n    racker run -it --rm registry.suse.com/suse/sle15 /bin/cat /etc/os-release\n    racker run -it --rm registry.suse.com/bci/bci-base:15.4 /bin/cat /etc/os-release\n    racker run -it --rm docker://ghcr.io/jpmens/mqttwarn-standard /usr/bin/hostnamectl\n\n    # Verbose mode.\n    racker --verbose run -it --rm fedora:37 hostnamectl\n\n    # Use stdin and stdout, with timing.\n    time echo \"hello world\" | racker run -it --rm fedora:37 cat /dev/stdin \u003e hello\n    cat hello\n\n\nPostroj\n=======\n\nThe idea behind ``postroj`` is to provide an entrypoint to a command line\ninterface implementing actions that don't fit into ``racker``, mostly having a\nmore high-level character.\n\nCurrently, ``postroj pkgprobe`` implements a flavor of *full system\nintegration/acceptance testing* in order to test the soundness of actual\ninstalled binary distribution packages, in the spirit of `autopkgtest`_.\n\nTo do so, it implements the concept of *curated* operating system images,\nwhose labels have a different layout than labels of Docker filesystem images.\n\nGetting started::\n\n    # List available images.\n    postroj list-images\n\n    # Acquire images for curated operating systems.\n    postroj pull debian-bullseye\n    postroj pull fedora-37\n\n    # Acquire rootfs images for all available distributions.\n    postroj pull --all\n\n    # Run a self test procedure, invoking `hostnamectl` on all containers.\n    postroj selftest hostnamectl\n\nPackage testing::\n\n    # Run a self test procedure, invoking example probes on all containers.\n    postroj selftest pkgprobe\n\n    # Run two basic probes on different operating systems.\n    postroj pkgprobe --image=debian-bullseye --check-unit=systemd-journald\n    postroj pkgprobe --image=fedora-37 --check-unit=systemd-journald\n    postroj pkgprobe --image=archlinux-20220501 --check-unit=systemd-journald\n\n    # Run probes that need to install a 3rd party package beforehand.\n\n    postroj pkgprobe \\\n        --image=debian-stretch \\\n        --package=http://ftp.debian.org/debian/pool/main/w/webfs/webfs_1.21+ds1-12_amd64.deb \\\n        --check-unit=webfs \\\n        --check-network=http://localhost:8000\n\n    postroj pkgprobe \\\n        --image=debian-bullseye \\\n        --package=https://dl.grafana.com/oss/release/grafana_8.5.1_amd64.deb \\\n        --check-unit=grafana-server \\\n        --check-network=http://localhost:3000\n\n    postroj pkgprobe \\\n        --image=centos-8 \\\n        --package=https://dl.grafana.com/oss/release/grafana-8.5.1-1.x86_64.rpm \\\n        --check-unit=grafana-server \\\n        --check-network=http://localhost:3000\n\n\n***********\nPerformance\n***********\n\nA SuT which just uses a dummy probe ``/bin/systemctl is-active systemd-journald``\non Debian 10 \"buster\" cycles quite fast, essentially demonstrating that the\noverhead of environment setup/teardown is insignificant.\n\n::\n\n    time postroj pkgprobe --image=debian-buster --check-unit=systemd-journald\n\n    real    0m0.589s\n    user    0m0.161s\n    sys     0m0.065s\n\nOn a cold system, where the filesystem image would need to be acquired before\nspawning the container, it's still fast enough::\n\n    time postroj pkgprobe --image=debian-bookworm --check-unit=systemd-journald\n\n    real    0m22.582s\n    user    0m8.572s\n    sys     0m3.136s\n\n\n*********************\nQuestions and answers\n*********************\n\n- | Q: How does it work?\n  | A: Directly quoting the `machinectl`_ documentation here:\n\n    Note that `systemd-run`_ with its ``--machine=`` switch may be used in place of the\n    ``machinectl shell`` command, and allows non-interactive operation, more detailed and\n    low-level configuration of the invoked unit, as well as access to runtime and exit\n    code/status information of the invoked shell process.\n\n    In particular, use ``systemd-run``'s ``--wait`` switch to propagate exit status information\n    of the invoked process. Use ``systemd-run``'s ``--pty`` switch for acquiring an interactive\n    shell, similar to ``machinectl shell``. In general, ``systemd-run`` is preferable for\n    scripting purposes.\n\n- | Q: How does it work, really?\n  | A: Roughly speaking...\n\n  - `skopeo`_ and `umoci`_ are used to acquire root filesystem images from Docker image registries.\n  - `systemd-nspawn`_ is used to run commands on root filesystems for provisioning them.\n  - Containers are started with ``systemd-nspawn --boot``.\n  - `systemd-run`_ is used to interact with running containers.\n  - `machinectl`_ is used to terminate containers.\n\n- | Q: How is this project related with Docker?\n  | A: The runtime is completely independent of Docker, it is solely based on\n       ``systemd-nspawn`` containers instead. However, root filesystem images can be\n       pulled from Docker image registries in the spirit of `machinectl pull-dkr`_.\n       Other than this, the ``racker`` command aims to be a drop-in replacement for\n       its corresponding ``docker`` counterpart.\n\n- | Q: Do I need to have Docker installed on my machine?\n  | A: No, Racker works without Docker.\n\n- | Q: How are machine names assigned?\n  | A: Machine names for spawned containers are automatically assigned.\n       The name will be assembled from the distribution's ``fullname`` attribute,\n       prefixed with ``postroj-``.\n       Examples: ``postroj-debian-buster``, ``postroj-centos-8``.\n\n- | Q: Does the program need root privileges?\n  | A: Yes, the program currently must be invoked with ``root`` or corresponding\n       ``sudo`` privileges. However, it would be sweet to enable unprivileged\n       operations soon. ``systemd-nspawn`` should be able to do it, using\n       ``--private-users`` or ``--user``?\n\n- | Q: Where does the program store its data?\n  | A: Data is stored at ``/var/lib/postroj``.\n       In this manner, it completely gets out of the way of any other images, for\n       example located at ``/var/lib/machines``. Thus, any images created or managed\n       by Racker will not be listed by ``machinectl list-images``.\n  | A: The download cache is located at ``/var/cache/postroj/downloads``.\n\n- | Q: Where are the filesystem images stored?\n  | A: Activated filesystem images are located at ``/var/lib/postroj/images``.\n\n- | Q: How large are curated filesystem images?\n  | A: The preference for curated filesystem images is to use their corresponding\n       \"slim\" variants where possible, aiming to only use artefacts with download\n       sizes \u003c 100 MB.\n\n- | Q: Are container disks ephemeral?\n  | A: Yes, by default, all container images will be ephemeral, i.e. all changes to\n       them are volatile.\n\n\n***************\nTroubleshooting\n***************\n\n*It's always the cable. ;]*\n\n1. If you see that your container might not have network access, make sure to\n   provide a valid DNS configuration in your host's ``/etc/resolv.conf``.\n   When in doubt, please add ``nameserver 9.9.9.9`` as the first entry.\n\n2. Sometimes, configuring an arbitrary name server is not permitted. An indicator\n   could be this configuration within ``/etc/resolv.conf``::\n\n       nameserver 127.0.0.53\n       options edns0 trust-ad\n\n   If that is the case, you can look up the trusted DNS servers by running\n   ``resolvectl status`` or ``resolvectl dns``. Then, use the DNS server listed\n   there to announce per ``nameserver \u003cdns host\u003e`` entry to your container's\n   ``/etc/resolv.conf``.\n\n\n.. _autopkgtest: https://www.freedesktop.org/wiki/Software/systemd/autopkgtest/\n.. _Chocolatey: https://chocolatey.org/\n.. _Comparison with similar tools - more details: https://github.com/cicerops/racker/blob/main/doc/comparison.rst\n.. _Container Tools Guide: https://github.com/containers/buildah/tree/main/docs/containertools\n.. _Container wars: https://github.com/cicerops/racker/blob/main/doc/research/container-wars.rst\n.. _Distrobox: https://github.com/89luca89/distrobox\n.. _Docker: https://github.com/docker/\n.. _machinectl: https://www.freedesktop.org/software/systemd/man/machinectl.html\n.. _machinectl pull-dkr: https://github.com/cicerops/racker/blob/main/doc/research/machinectl-pull-dkr.rst\n.. _nerdctl: https://github.com/containerd/nerdctl\n.. _Microsoft Container Registry: https://mcr.microsoft.com/\n.. _mkosi: https://github.com/systemd/mkosi\n.. _OCI Distribution Specification: https://github.com/opencontainers/distribution-spec\n.. _OCI Image Format: https://github.com/opencontainers/image-spec\n.. _OS containers: http://0pointer.net/blog/systemd-for-administrators-part-xxi.html\n.. _OS-level virtualization: https://wiki.debian.org/SystemVirtualization#OS-level_virtualization\n.. _Packer: https://www.packer.io/\n.. _Podman: https://podman.io/\n.. _Racker sandbox installation: https://github.com/cicerops/racker/blob/main/doc/sandbox.rst\n.. _skopeo: https://github.com/containers/skopeo\n.. _systemd: https://www.freedesktop.org/wiki/Software/systemd/\n.. _systemd-nspawn: https://www.freedesktop.org/software/systemd/man/systemd-nspawn.html\n.. _systemd-nspawn in a nutshell: https://github.com/cicerops/racker/blob/main/doc/systemd-nspawn.rst\n.. _systemd-run: https://www.freedesktop.org/software/systemd/man/systemd-run.html\n.. _Toolbox: https://containertoolbx.org/\n.. _umoci: https://github.com/opencontainers/umoci\n.. _Vagrant: https://www.vagrantup.com/\n.. _Vagrant Cloud: https://app.vagrantup.com/\n.. _Windows Docker Machine: https://github.com/StefanScherer/windows-docker-machine\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyveci%2Fracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpyveci%2Fracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpyveci%2Fracker/lists"}