Contributing

nspawn is developed on GitHub under the nspawn organization:

Issues and pull requests are welcome in all of them. The code of conduct applies everywhere.

Working on the tool

A Rust toolchain of version 1.85 or newer is enough for the unit tests and clippy:

cargo test
cargo clippy --all-targets -- -D warnings
cargo build --release

The end-to-end test runs the built binary against a real registry and systemd-machined, as root, on a host with systemd-nspawn:

NSPAWN=./target/release/nspawn sudo -E tests/e2e.sh

It exercises the whole tool: hub ls, search on the hub and on Docker Hub, login and logout, a pull with both the overlay and the flat backend, booting, exec through the PTY, volumes, the bridge network with names and published ports between two machines, create from a local image, layer sharing and garbage collection, an app from Docker Hub with entrypoint, environment and volumes, machinectl start through the unit hooks, programs that exit on their own or ignore their stop signal, and (when mkosi is installed) a build, push and pull round trip. NSPAWN_REGISTRY (and NSPAWN_CA_CERT for a private CA) must point at a registry that serves the image named in IMAGE, fedora:44 by default; the Docker Hub steps need internet access.

Keep pull requests focused, add a unit test when the change has logic that can be tested without a host, and run clippy before sending.

Working on the images

The images are plain mkosi configuration trees. Changes to what the hub ships, new distributions or releases go to mkosi-definitions. A definition can be tried locally with nspawn build -t test/NAME:1 DIRECTORY before sending it.

Working on this site

The site is built with Hugo and the Docsy theme. With Docker installed, a live preview needs nothing else:

git clone https://github.com/nspawn/website.git
cd website
docker compose up

Then open http://localhost:1313. The container runs as uid and gid 1000; the README of the repository explains how to pass yours if they differ. Without Docker, install Node.js, Go and git and run npm run install:safe followed by npm run serve. The pages are Markdown files under content/en/; every documentation page has an “Edit this page” link that opens the file on GitHub.