Skip to content

Native packages for Ubuntu, Fedora/RHEL and Arch; dzo as a container appliance - #10

Merged
bzed merged 33 commits into
mainfrom
feature/linux-distributions
Nov 21, 2026
Merged

bzed merged 33 commits into
mainfrom
feature/linux-distributions

Conversation

@bzed

@bzed bzed commented Nov 21, 2026

Copy link
Copy Markdown
Owner

Implements the two designs from docs/superpowers/specs/2026-11-21-*-design.md, following the plans in docs/superpowers/plans/.

Native packages

  • htmx 2.0.4, Leaflet 1.7.1, Fork Awesome 1.2.0 and the country flags are vendored (scripts/vendor-web.sh, pinned sha256) and embedded. web.assets / web.flags_dir default to empty and override the embedded files one at a time.
  • The .deb no longer depends on libjs-htmx, libjs-leaflet, fonts-fork-awesome, iso-flags-svg or libjs-sphinxdoc.
  • apt publishes a stable suite. package-install CI runs on trixie and Ubuntu 26.04 (both blocking), and on Ubuntu 26.10 and forky (non-blocking).
  • dzo setup refuses podman older than 5.4.
  • One shared post-install script, /usr/libexec/dzo/postinst, which picks a free subuid range.
  • A steamcmd wrapper for hosts without steamcmd runs it from the dzo-steamcmd image. Adds dzo config get.
  • rpm and signed dnf repo for Fedora 43/44 and the RHEL 10 family.
  • PKGBUILD and signed pacman repo for Arch (best effort).
  • scripts/check-quadlet.sh runs each distribution's quadlet generator (podman 5.4–6.2) over the rendered units.
  • Support matrix and a manual release checklist.

Container appliance

  • podman.mode: remote turns instances into supervised dzo-<name>.service units (Type=notify). The podman run arguments are written into ExecStart, so a held unit still holds them. A parity test keeps them in step with the quadlet.
  • A mode switch never stops a running server.
  • dzo instance supervise: runs or re-attaches, sends READY=1 on healthy, and stops the container on SIGTERM. The appliance-tagged integration test (make test-appliance) runs against a real podman socket.
  • The health-check binary is copied below paths.data, and dzo setup gains three remote checks.
  • The boot test's working directory moves below paths.data.
  • New: images/appliance, contrib/appliance (host quadlet + wrapper), docs/container.rst.

Testing

  • make check passes locally, including browser e2e. Coverage is 86.1%.
  • The rpm and Arch packages were install-tested in containers; the appliance in an end-to-end run on a dev workstation with a stand-in container.
  • None of the new or changed CI jobs had run on GitHub before this push, so they may need follow-ups. The S3 sync step will fail; that is being fixed separately.

Not verified yet (manual checklist)

  • SELinux enforcing on Fedora/RHEL.
  • A real Steam login through the steamcmd wrapper.
  • A real DayZ server through the appliance.
  • The 24 h long-attach spike result.

🤖 Generated with Claude Code

bzed and others added 28 commits November 21, 2026 00:56
…ainer appliance

Two specs, both drafts waiting for approval:

- Native packages: the .deb for Ubuntu 26.04 LTS and later, a dnf
  repository for Fedora and the RHEL 10 family, a pacman repository for
  Arch. The web assets move into the binary so no package depends on
  distribution copies of htmx, Leaflet, Fork Awesome and the flags.
- The appliance: Debian trixie with systemd as init in a podman
  container, managing game servers through the host user's podman
  socket. Quadlets do not work through the socket (--cgroups=split is
  refused in remote mode), so instances get a plain unit and a
  supervisor in that mode only.

Both record what was checked in throwaway containers on 2026-11-20 and
what is still open.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…appliance

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The web interface's JavaScript, CSS, images and fonts move into the tree
with pinned versions (htmx 2.0.4, Leaflet 1.7.1, Fork Awesome 1.2.0, the
ones Debian trixie ships) and a SHA256SUMS list next to them.
scripts/vendor-web.sh (`make vendor-web`) downloads the upstream release
archives, verifies the digest of every archive, extracts only the files
the pages reference and checks the result against the sums; --update
rewrites them after a version bump. Nothing is downloaded during a build.

The country flags are not vendored: iso-flags-svg collects them under the
Creative Commons Public Domain Dedication, which the `licenses` allow-list
of the Makefile does not cover, so web.flags_dir keeps serving them from
the installed package (step 1 of the task's contingency; see the report).

Licences: LICENSES/ gains 0BSD (htmx), BSD-2-Clause (Leaflet) and MIT
(Fork Awesome's CSS), the fonts are OFL-1.1 which was already there, with
one REUSE.toml annotation per project and one debian/copyright stanza.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
The country flags join the vendored web files: the 4:3 SVGs of the
linuxmint ISO country flags SVG collection, the set Debian's
iso-flags-svg is built from, in internal/web/vendor/flags/<code>.svg.
252 files, 4.5 MiB. Debian's `licenses` allow-list governs the Go module
dependencies only, so it never ruled them out: the flags are public
domain (the Creative Commons Public Domain dedication in each SVG's RDF
metadata, no copyright claimed), which is compatible with the AGPL.

The collection ships no release tags, so scripts/vendor-web.sh pins the
newest commit on master (f2cf92fc2fb200a9132b39672091fc6717a3ad32,
2025-07-16) and the sha256 of its GitHub tarball, like the npm tarballs.
It extracts only svg/country-4x3/[a-z][a-z].svg, so the square flags,
regions and organisations (_scotland.svg, _united_nations.svg, ...) and
the three-letter brl.svg stay out — the flag handler looks up nothing
else — and fails when the archive yields anything that is not <code>.svg
for a two-letter code. SHA256SUMS is rewritten with --update.

Licence: LICENSES/LicenseRef-PublicDomain.txt records the dedication,
REUSE.toml annotates internal/web/vendor/flags/** with
LicenseRef-PublicDomain, and debian/copyright gains a Files stanza with
the matching public-domain text. The "flags are not vendored" note is
gone from scripts/vendor-web.sh, docs/development.rst and the Makefile.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…sets and web.flags_dir override them

The web files vendored in internal/web/vendor are compiled into dzo and
served as the default under /vendor/ and /flags/. SHA256SUMS stays out of
the embed.

web.assets and web.flags_dir are now optional overrides that work file by
file: a file the directory holds wins, a file it lacks comes from the
binary. A configured directory that is not there logs one warning when
`dzo web` starts and falls back to the built-in copies, so an existing
config pointing at /usr/share/javascript keeps working after the Debian
packages are gone.

/vendor/ serves no directory: no listing and no index.html. The flag
handler keeps its two-letter validation and still lowercases the code,
because the pages use GeoIP's upper-case code.

The e2e suite uses the built-in files unless DZO_E2E_ASSETS is set, and the
docs describe the new defaults, the overlay and the optional test assets.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
With web.assets empty by default, admin.IconNames read nothing and the
unknown-icon warnings of dzo site validate silently disappeared.

web.VendorFile reads a file through the same overlay the /vendor/ handler
serves: the configured directory first, the copy compiled into dzo for a
file it lacks. dzo site validate now reads fork-awesome/css/fork-awesome.css
that way and hands the content to admin.IconNames, which no longer touches
the file system, so an override still decides which icons are known.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…some, iso-flags-svg

The web interface has served the htmx, Leaflet, Fork Awesome and country
flags compiled into the binary since web: serve the built-in htmx,
Leaflet, Fork Awesome and flags, and web.assets and web.flags_dir default
to empty. The packages were only worth their Depends: entry until then, so
the .deb drops them; an existing configuration that still names
/usr/share/javascript or /usr/share/iso-flags-svg/country-4x3 keeps
working from the built-in copies, with the one warning at start.

The e2e job and images/e2e/Containerfile install Chromium alone now. The
forky run is no longer allowed to fail: the htmx 4 beta it warned about is
irrelevant to a dzo that brings its own htmx, so forky tests the browser
of the next Debian release like trixie tests this one.

README, docs/installation.rst and docs/development.rst no longer say the
package needs Debian's web libraries, and IMPLEMENTATION_PLAN.md's design
sections describe the compiled-in copies.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
- scripts/build-apt-repo.sh runs `reprepro createsymlinks`, so the published
  repository answers `Suites: stable` (dists/stable -> dists/trixie) next to
  the codename it already had.
- The package-install CI job becomes a matrix: debian:trixie and ubuntu:26.04
  are blocking, ubuntu:26.10 and debian:forky are continue-on-error. It
  enables multiverse on Ubuntu instead of Debian's contrib/non-free, and
  checks that dayz is a regular user (UID 1000+) with subordinate uid/gid
  ranges.
- The installation guide and the README use `Suites: stable` and gain an
  Ubuntu 26.04 LTS section; development.rst documents the symlink and why.

Verified locally: reprepro built the repository with dists/stable -> trixie
and apt resolved dzo 0.8.2-1 from both suites with the signature checked; a
.deb built as in the deb job (debian:trixie) installs in ubuntu:26.04 and
ubuntu:26.10, and `dzo version`, `dzo setup --dry-run` as dayz and the
uid/subuid checks exit 0 in both; lintian --fail-on error is clean;
actionlint, make fmt-check/vet/lint/reuse, make docs and go test ./... pass.
Nothing is pushed, so the workflow itself could not run.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…ending on libjs-sphinxdoc

dh_sphinxdoc replaced the JavaScript in the built HTML with symlinks into
/usr/share/javascript/sphinxdoc and pinned ${sphinxdoc:Depends} to the
Sphinx version that built the package. One .deb is published for Debian 13
and Ubuntu 26.04 LTS, so a package built by Debian's next Sphinx would
refuse to install on Ubuntu 26.04, whose libjs-sphinxdoc is older - the
same failure a host build with Sphinx 9.2 hit here.

Do not run dh_sphinxdoc: the HTML keeps the JavaScript and CSS that Sphinx
itself writes into _static, the way dzo ships htmx, Leaflet, Fork Awesome
and the flags itself. The dependency is gone and the pages work the same
(the /docs/ handler serves them from DocsDir). Lintian's
embedded-javascript-library warnings ("please use sphinx") are the expected
cost, and they are warnings, not errors.

- debian/control: drop dh-sequence-sphinxdoc and ${sphinxdoc:Depends}
- .github/workflows/ci.yml: no dh-sequence-sphinxdoc in the deb job
- verified: dpkg-deb -f Depends has no libjs-sphinxdoc, _static/*.js are
  real files (no symlinks) and the package installs in ubuntu:26.04

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
The package depends on podman 5.4, but an older one (for example a
locally installed podman, or a host where the user put an ancient
release in PATH) would fail later, during the image build or in the
rootless quadlet setup, with errors that do not point at the version.

dzo setup now runs `podman version --format {{.Client.Version}}` first
and refuses anything below 5.4 with "podman <version> is too old: dzo
needs podman 5.4 or newer". There is no upper bound, a suffix such as
5.8.6-dev is accepted, and an unparsable version is an error. The
check only reads a version, so --dry-run does it too, and
--images-only (the weekly timer) gets it as its only pre-build check.
A failed check skips the steps that would only repeat the failure.

checkPodmanVersion takes the raw output and has no side effects, so a
later task can reuse it for the server's podman.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…id range

The steps every package needs after installing (create /var/lib/dzo, give
dayz a subuid/subgid range, enable lingering, and on an upgrade refresh the
units and restart dzo's own services) move from debian/postinst into
packaging/common/dzo-postinst.sh, installed as /usr/libexec/dzo/postinst.
The .deb runs it from its postinst after the debhelper snippets, so the dayz
user from sysusers.d exists; the rpm %post and the Arch .install hook will
call it directly and cannot drift from the .deb. "upgrade" repeats the
configuration and adds the unit sync and restarts, so an upgrade is also a
first configuration.

The subordinate id range is no longer hard-coded to 100000-165535: the script
takes the lowest block of 65536 ids at or above 100000 that overlaps no line
of /etc/subuid resp. /etc/subgid (chosen independently, one usermod call),
so the package installs on a host where another rootless podman user already
holds the old fixed range. A range dayz already has is left alone, so a
running instance's container namespace mapping never changes.

dzo.sysusers and dzo.tmpfiles move to packaging/common and are installed for
the .deb through symlinks in debian/, which keeps the names
/usr/lib/sysusers.d/dzo.conf and /usr/lib/tmpfiles.d/dzo.conf.

DZO_ROOT prefixes every path the script touches; internal/packaging runs it
in `make test` against a temporary root with fake usermod, loginctl,
install, id and runuser commands that log their arguments. The .deb was
installed in debian:trixie locally (fresh install and a host where alice
already owns 100000-165535: dayz gets 165536), lintian is clean.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
On Fedora, RHEL and Arch there is no steamcmd package, so the mod and
product downloads and `dzo steam login` now fall back to
/usr/libexec/dzo/steamcmd-container, which runs steamcmd from the
localhost/dzo-steamcmd image `dzo setup` builds. A host steamcmd still
wins; --steamcmd (mod add/update/refresh, product install/update) and
dzo steam login --command pick another program explicitly.

The wrapper mounts the steamcmd home (<paths.secrets>/steamcmd-home,
created 0700) and paths.cache into the image at the same paths, so
steamcmd's self-update, the Steam session and the +force_install_dir work
directories persist; it passes -t only when its stdin is a terminal,
which is what `dzo steam login`'s pty needs, and exits 1 with
"dzo-steamcmd image missing: run dzo setup" when the image is gone. It
reads both paths from the new `dzo config get <key>` instead of parsing
config.yaml, so a non-default paths block works.

`dzo setup` reports which steamcmd the downloads use.

Verified: make fmt, vet, lint, reuse; go test ./... (make cover: 86.0%,
minimum 85%); make docs. The wrapper ran steamcmd to +quit from the
built image with a temporary config under /var/tmp, through a pipe and
through a pty. dpkg-buildpackage -us -uc -b and lintian passed in a
debian:trixie container; the deb installs
/usr/libexec/dzo/steamcmd-container mode 0755.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
dzo writes the .container quadlets itself (internal/quadlet) instead of calling
`podman generate systemd`, so only podman's own generator can tell whether the
podman of a distribution still accepts the keys it emits - no Go test can.
scripts/check-quadlet.sh probes for the generator of the installed podman (the
systemd user generator, or the quadlet binary with -user), takes the rendered
units out of the golden files of internal/resolve, runs the generator as a
dryrun with QUADLET_UNIT_DIRS pointed at them, and fails on a non-zero exit, an
unsupported key or option, or a unit the generator skipped instead of
converting. The dryrun only converts: the volume sources and the image of the
units need not exist.

New quadlet-check job over debian:trixie (podman 5.4, the minimum) and
fedora:44, both blocking, and centos:stream10 and archlinux, which carry
podman 6 and are continue-on-error; each package-install job runs it as well,
against the podman the package pulls in. Measured while writing it: podman
5.4.2, 5.8.9 (Fedora 44), 6.1.0 (CentOS Stream 10) and 6.2.0 (Arch) convert
both units without a warning, so no key needed to change.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
The rpm repackages what CI already builds: the static binary from the build
job and the payload the deb job uploads as dzo-payload (servermods, images,
presets, the HTML documentation, the generated man pages, the cheat sheet).
packaging/rpm/dzo.spec only copies them into place, so the rpm and the .deb
ship the same files and no Go toolchain is needed on a Fedora build host.
scripts/build-rpm.sh assembles the tree and runs rpmbuild in a throwaway
_topdir under /var/tmp.

Version: the upstream version from the top debian/changelog entry, the Debian
revision as the rpm release, and "+git<commits>.<sha>" appended to the release
for snapshot builds, the same string scripts/debian-snapshot.sh puts in the
.deb. rpm orders that exactly like dpkg (0.8.2-1 < 0.8.2-1+git43.abc1234 <
0.8.2-2; checked with rpm's vercmp). The brief asked for "~" instead; that
sorts *before* the release, so `dnf upgrade` on a release install would never
pick up the main snapshots that `apt upgrade` does, which is the opposite of
"sort it like dpkg".

The dayz user is created in %pre, not by a packaged sysusers.d file. Fedora 43
and 44 (rpm 6.0.2) process that file before %pre and allocate a system UID
(999) even with "r - 1000-59999"; CentOS Stream 10 (rpm 4.19.1.1) does not
process it at install time at all (systemd's file trigger creates the user at
the end of the transaction, after %post, and %sysusers_create_compat expands to
useradd -r). dzo needs a regular user so journald keeps a journal of its own
for `dzo logs`, so %pre takes the first free UID at or above 1000 and leaves an
existing dayz user alone. The .deb keeps its sysusers file.

The dnf repository is built by scripts/build-rpm-repo.sh: rpmsign signs every
package with the key in GNUPGHOME, createrepo_c writes the metadata, and
repodata/repomd.xml gets a detached signature for repo_gpgcheck. The Docs
workflow publishes it under /rpm/ next to /apt/, from the dzo-rpm artifact.
rpm --import accepts the existing apt key (EdDSA) on Fedora 43/44 and CentOS
Stream 10, so both repositories use the same key and APT_GPG_PRIVATE_KEY;
rpm/dzo-repo-keyring.asc is a copy of the apt public key and the workflow fails
if the two differ. rpm/dzo.repo points at the repository with gpgcheck=1 and
repo_gpgcheck=1.

CI gets a rpm job (Fedora 44, rpmlint with packaging/rpm/dzo.rpmlintrc, which
filters only what a Go package cannot change: the static binary and DayZ in
rpmlint's spelling data) and a blocking rpm-install job over fedora:43,
fedora:44 and centos:stream10: dnf install, dzo version, the quadlet generator
check, dzo setup --dry-run as dayz, and the UID >= 1000 and subuid/subgid
checks. The deb job now uploads dzo-payload.

The docs get the Fedora/RHEL section: repository, dnf install, no btrfs on the
RHEL 10 family (no snapshot backups), and that SELinux is not verified yet:
the game containers and the steamcmd wrapper (no :z relabelling) may hit AVC
denials, checked with `ausearch -m avc -ts recent`. Task 8's SELinux spike
could not be run, so the quadlets are untouched. Task 7's manual result is also
missing: the real Steam login through the wrapper is still untested.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
packaging/arch/PKGBUILD repackages what CI already built, exactly like
packaging/rpm/dzo.spec: the static binary of the build job and the dzo-payload
artifact the deb job uploads (servermods, images, presets, the HTML
documentation, the generated man pages, the cheat sheet). Nothing is compiled
here, so the .deb, the rpm and the Arch package ship the same files and an Arch
build host needs no Go toolchain. The files under packaging/common/ come from the
checkout, so the formats cannot drift.

Version: pkgver is the upstream version of the top debian/changelog entry, pkgrel
the Debian revision, and a snapshot build appends the number of commits since
the last tag to pkgrel (0.8.2-1.43). pacman's vercmp orders that exactly like
dpkg and rpm do (0.8.2-1 < 0.8.2-1.43 < 0.8.2-2 < 0.8.3-1; verified with vercmp
in archlinux:latest). The brief's "."-in-pkgver variant (0.8.2.git43.abc1234)
sorts after the release but also after 0.8.2-2, so a packaging fix would never
reach a host on a snapshot; pkgrel takes "integer[.integer]" only, so the sha
cannot be in the version at all. "dzo version" prints the commit.

The account: Arch's systemd-sysusers hook runs in the post-transaction hooks,
after post_install, so postinst would not find the dayz user yet (measured in
archlinux:latest: "Preparing package changes" -> post_install -> "Creating
system user accounts"). The packaged sysusers.d file itself behaves like
Debian's: with "r - 1000-59999" it allocated UID 59999, a regular user, and the
hook finds the account on the next run. dzo.install therefore calls
systemd-sysusers itself before /usr/libexec/dzo/postinst configure|upgrade, which
keeps packaging/common/dzo.sysusers the one description of the account. The rpm
had to create the user in %pre because rpm's own sysusers handling allocates a
system UID below 1000.

scripts/build-arch-repo.sh signs every package with a detached signature (gpg
--detach-sign), runs "repo-add --sign" and publishes the database as dzo.db and
its signature as dzo.db.sig. repo-add writes both as links into dzo.db.tar.gz,
and GitHub Pages serves a static tree, so the script replaces them with regular
files; libalpm detects the gzip database under the dzo.db name. It also writes
arch/dzo-repo-keyring.asc (the public apt/rpm key, so one key covers all three
repositories) and copies arch/dzo.conf next to it: the [dzo] stanza with
"SigLevel = Required DatabaseRequired". Tested locally with a throwaway key:
pacman-key --add + --lsign-key, pacman -Sy and pacman -S dzo from an HTTP server,
a signature over other data is rejected ("signature ... is invalid"), a missing
dzo.db.sig is refused, and pacman -S dzo works again afterwards.

CI gets an arch job (archlinux:latest, pacman -Syu first because a partial
upgrade conflicts, makepkg as a non-root build user with --nodeps since the
package only assembles prebuilt files, namcap failing on errors only: no errors,
the warnings are the prebuilt static binary, /usr/libexec and the dependencies of
a package without compiled code) and an arch-install job (pacman -U, dzo version,
the quadlet generator check, UID >= 1000 and subuid/subgid checks, and
dzo setup --dry-run as dayz last, so a namespace failure in the container cannot
hide the others). Both are continue-on-error: Arch is a rolling release. The
install test inside archlinux:latest passes all checks; dzo setup --dry-run stops
at newuidmap ("could not set caps") in a nested container, a limitation of the
podman test setup, not of the package.

The Docs workflow publishes the repository under /arch/ from the dzo-arch-pkg
artifact, signed with the same APT_GPG_PRIVATE_KEY secret and checked against
arch/dzo-repo-keyring.asc. The docs get an "Arch Linux (best effort)" section
(pacman.conf Include, pacman-key --add/--finger/--lsign-key, how pkgrel orders a
snapshot) and the pacman repository notes in the development page. namcap's
cross-directory hardlink error is avoided by shipping the cheat sheet twice (the
rpm hardlinks it); the package ships no sysusers hook warning-free, see above.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
Add the support matrix the distribution work implies, with the level a
distribution is tested at rather than the level it might work at:

* docs/installation.rst gets a "Support levels" table (reference:
  Debian 13; supported: Ubuntu 26.04 LTS, Fedora 43/44, the RHEL 10
  family; best effort: Arch, Ubuntu interim releases, Debian testing), a
  table of the CI job in each distribution's image and whether it blocks
  a merge, a "What CI cannot check" section (SELinux in enforcing mode,
  the interactive Steam login through the steamcmd container wrapper,
  podman 6, Arch, no btrfs on the RHEL 10 family) and a requirements
  table per distribution instead of one bullet list.
* docs/development.rst gets "Release checklist for other distributions":
  the eight manual steps from the installation to an upgrade with a
  server running, on a VM, once per release line and when a distribution
  release joins the matrix.
* README.md drops "on Debian" from the headline and the summary and shows
  the matrix; docs/index.rst and docs/overview.rst stop calling the host
  a Debian machine; docs/dev-host.rst says that it is Debian-specific and
  links the matrix.
* IMPLEMENTATION_PLAN.md: the packaging test row now lists what CI really
  builds and installs where.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
Add podman.mode (local|remote, default local) with validation and
Remote() accessor, plus the documented config.yaml key. Remote mode
itself is implemented by later tasks.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
… quadlet's podman arguments

With podman.mode: remote an instance is no longer a quadlet of this host's
podman: dzo units sync writes a plain systemd user unit dzo-<name>.service
whose ExecStart runs dzo instance supervise <name> (a later change; the unit
and the run arguments are built here). The supervisor runs
`podman RunArgs(spec)`, so quadlet.RunArgs mirrors key by key what
RenderContainer emits; TestRunArgsMatchesQuadlet fails on a [Container] key it
does not know, so a new key forces a decision. The [Unit], [Service] and
[Install] writers RenderContainer used are shared with RenderSupervised, so a
mode switch keeps the instance's life cycle, and local mode renders the same
bytes as before (the resolve goldens are unchanged).

Sync also learns the two things a plain instance unit needs: a held pending
update is looked up in the directory of the unit's own mode (nothing is held
across a mode switch, which writes the new unit instead), and a removed
instance unit is never disabled -- disabling it would stop a running game
server when switching back to local mode. File.Install makes Sync call the
new Lifecycle.Enable (systemctl --user enable, no --now), so a supervised
unit comes back after a reboot without a sync ever starting a server.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…d unit holds them

In podman.mode remote ExecStart was just `dzo instance supervise <name>`:
the supervisor resolved the instance when it started. A held unit (an update
is pending, so dzo units sync keeps its file) therefore held nothing. When
systemd restarted a crashed server it resolved the current cache instead, so
the pending update was applied silently, and because Sync skips Record for a
held unit it was never recorded either. Local mode has no such hole: the
quadlet's paths name the generations.

RenderSupervised now writes `<execStart> -- <podman run arguments>` with
RunArgs(spec), each word quoted for systemd's ExecStart parsing, so the unit
carries the container it was rendered for, exactly like a quadlet. quoteWord
gained C escapes for control characters, so no argument can end the directive
line; a quoted lone ';' stays one argument (checked with systemd-analyze
verify). RunArgs validates the spec for RenderSupervised too.

Tests: TestRenderSupervisedService and TestDesiredRemoteWritesService expect
the arguments in ExecStart, TestRenderSupervisedExecStartRoundTrip unquotes
the line for alpha, beta and a spec of nasty values (whitespace, both quote
characters, %, $HOME, backslashes, a lone ';', an empty word, control
characters) and requires execStart + `--` + RunArgs exactly, and
TestSyncRemoteHoldsPendingUpdate now checks that a held unit keeps the g1
arguments and that deploying writes g2. The resolve goldens (local mode) are
unchanged.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…paths.data

In podman.mode remote the game containers are created by the host's
podman, so the health-check binary they mount at /usr/local/bin/dzo
cannot be the appliance's own /usr/bin/dzo. resolve.HealthBinary names
the mount source: the configured binary in local mode (quadlet goldens
unchanged), <paths.data>/bin/dzo in remote mode, a path the data
directory makes visible on the host and in the appliance alike.

units.Sync, in remote mode and not in a dry run, copies cfg.Binary there
before it writes any unit: content compared first, then a temporary file
in the same directory, fsynced, 0755 and renamed into place, so a unit
never names a missing or half-written binary. A bind mount pins the
inode, so a running container keeps the binary it started with across an
apt upgrade, as on a native install; no versioned copies are kept.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…te podman

The supervisor is the ExecStart of a supervised instance unit
(podman.mode: remote): it runs the container the unit carries after a `--`
verbatim, or attaches to it when it already runs, reports READY=1 to
systemd once the container's health check is healthy, stops the container
when systemd stops the unit, and exits with the container's exit code.

A broken podman connection (the container outlived its client) attaches
again instead of failing the unit; a stopped container is replaced. The
podman socket is probed before anything runs, so a down socket fails the
unit fast instead of hanging until the start timeout.

The run arguments are not rendered again from the instance: a held unit
keeps the generations it was rendered for across a systemd restart, as a
held quadlet does.

Tested with a fake podman in internal/supervise and, against the real
rootless podman socket on this host, with `make test-appliance`
(DZO_APPLIANCE_PODMAN=1).

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…ystemd

In podman.mode remote, dzo setup now also reports the three things the
container appliance depends on: the podman server (not just the local
client) is version 5.4 or newer, the host's podman uses systemd cgroups
(without them the instance health checks never run), and paths.data is
mounted on the host at the same path. The last check writes a random
private file below paths.data and reads it back in the runtime image;
a dry run skips the container with an info line, since the other two
checks are read-only.

The boot test's run tree moves below paths.data in remote mode
(<paths.data>/boottest/<stamp>): the host's podman mounts that tree but
cannot see ~/.cache/dzo/boottest. The design note is corrected too: the
boot test does not mount its token directory, it mounts the run tree.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
The image CI builds from the .deb of the same run and pushes to
ghcr.io/bzed/dzo: Debian trixie with systemd as PID 1, the image's dayz
user at UID/GID 1000 created before the package is installed (so the
package's sysusers.d file leaves it alone) with lingering on, dzo's apt
repository for updates from inside, and podman in remote mode against the
host's user socket mounted at /run/host-podman.sock.

USER 0 is what makes the options of the host quadlet work: with
--userns keep-id podman runs the container as the mapped user (1000)
unless the image asks for root, and systemd in system mode must be PID 1
as root. dayz stays the host user on the mounted data directory.

The new CI job builds the image from the dzo-deb artefact after
package-install, boots it with the quadlet's options, checks that systemd
is running, that the user manager holds CONTAINER_HOST, that podman as
dayz reaches the host's containers and that dzo setup --dry-run passes,
and pushes the version and latest tags on main and release tags. A weekly
schedule rebuilds it for Debian security updates.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
contrib/appliance/dzo.container is the systemd user unit that runs the
image as an appliance: host networking, keep-id to the host user (the
image's USER 0 must stay; keep-id would otherwise run systemd as UID
1000 and it dies), the user's podman socket at /run/host-podman.sock,
/srv/dzo at the same path on both sides, named volumes for /etc/dzo,
/var/lib/dzo and /var/log/journal, and StopTimeout=90 (the default
stop.timeout of 30 s plus 60).

contrib/appliance/dzo runs dzo inside the appliance as dayz with
XDG_RUNTIME_DIR and the dayz home, -it only when stdin is a terminal;
DZO_CONTAINER overrides the container name.

End-to-end on this host (image localhost/dzo-appliance:e2e built from
the 0.8.2-1 .deb, unique unit/container names and a throwaway data
dir): dzo setup reported ok for the three remote checks (podman server
5.8.6, paths.data at the same path, systemd cgroups); a supervised
stand-in unit (Type=notify, quadlet.RenderSupervised, debian:trixie-slim
sleep infinity) became active only when the container was healthy
(4.7 s); podman kill of the appliance left the server running and the
enabled unit re-attached after the appliance start (podman attach
--no-stdin, StartedAt unchanged); apt install --reinstall of the same
.deb left the unit and its old binary in place (StartedAt unchanged,
/usr/bin/dzo (deleted) for the supervisor); podman stop stopped the
server first (user journal: Stopping dzo-e2e1.service) and the --rm
container was gone within the StopTimeout.

The quadlet's container runs with --rm, so podman stop/kill remove the
appliance container: after a kill or stop, the unit (systemctl --user
start dzo.service) is the way back. That, and the real-server run (RCon
shutdown, a joining client), are on the new manual checklist in
docs/development.rst; CI has no Steam login or DayZ.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
docs/container.rst is the page for running dzo in the ghcr.io/bzed/dzo
appliance: the host requirements (rootless podman 5.4 or newer with
systemd, the user's podman.socket, lingering, systemd cgroups, btrfs for
the snapshot backups), the security note on the mounted socket, the host
quadlet and wrapper from contrib/appliance/, the same-path rule for the
data directory, how a supervised instance runs in podman.mode remote
(including the health-check binary copy and the boot test), what differs
from a native install (host containers, hooks with the image's tools, the
console in the host's podman logs when no supervisor is attached, the
host's podman.service restart), updating with apt inside, and what to do
for each of the three setup checks.

contrib/appliance/dzo.container gains a [Service] section:
TimeoutStopSec=150 (StopTimeout + 60 s, both must cover the sum of the
instances' stop timeouts plus 60 s) and Restart=on-failure, so a crashed
or killed appliance comes back without a login. The quadlet generator
merges both (checked with podman's quadlet -dryrun).

Linked from the index toctree, the installation page (both its container
section and its dzo setup list), the README install section, the
podman.mode prose in configuration.rst and the instance-unit paragraph in
operations.rst. development.rst mentions make test-appliance and lets
Restart=on-failure bring a killed appliance back in the release
checklist. docs/cli.rst needs no change: dzo instance supervise is hidden
and gen-man skips hidden commands (148 man pages, none of them for
supervise). debian/changelog has a bullet for the page and the quadlet.

make docs passes without warnings and podman.mode turns up in the
configuration example and in the prose.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
…unit's arguments

ParseUnitArgs scanned every word after `--`, so a game server argument
spelled --name overrode the container name, and a later --stop-timeout
shortened the grace the unit gives the server. Only the first occurrence
of each flag counts now: quadlet.RunArgs puts --name right after run and
--stop-timeout before the image, later words belong to the server's Exec
argument list.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
geoip.rst still described the legacy GeoIP.dat as a Debian dependency
of every install. Only the .deb depends on geoip-database; the rpm and
the Arch package ship no database and recommend geoipupdate, and Arch
packages geoip-database separately. Say which files each family
provides, where they land by default (serve.geoip_dir, the mmdb
directory geoipupdate writes, and serve.geoip_legacy_dir), and keep the
trixie-backports instructions for Debian 13's 2019 data.

Co-Authored-By: DeepSeek V4.1 Flash <noreply@deepseek.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@codecov

codecov Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 87.54153% with 75 lines in your changes missing coverage. Please review.
✅ Project coverage is 86.58%. Comparing base (1ca2722) to head (4c5fb54).
✅ All tests successful. No failed tests found.

Files with missing lines Patch % Lines
internal/setup/setup.go 78.49% 20 Missing ⚠️
internal/supervise/supervise.go 89.07% 20 Missing ⚠️
internal/units/units.go 71.69% 15 Missing ⚠️
cmd/dzo/config.go 82.75% 5 Missing ⚠️
cmd/dzo/main.go 0.00% 3 Missing ⚠️
cmd/dzo/supervise.go 86.36% 3 Missing ⚠️
cmd/dzo/testboot.go 71.42% 2 Missing ⚠️
internal/supervise/notify.go 87.50% 2 Missing ⚠️
cmd/dzo/shortcuts.go 80.00% 1 Missing ⚠️
internal/config/config.go 87.50% 1 Missing ⚠️
... and 3 more
Additional details and impacted files
@@            Coverage Diff             @@
##             main      #10      +/-   ##
==========================================
+ Coverage   86.56%   86.58%   +0.01%     
==========================================
  Files         215      221       +6     
  Lines       21237    21767     +530     
==========================================
+ Hits        18384    18846     +462     
- Misses       2843     2911      +68     
  Partials       10       10              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

The supervisor's copy in the appliance's journal has gaps (no supervisor
attached, or a restart of the host's podman.service, which does not resume
the attached stream). The host's journal, podman's journald log driver,
has all of it. Records the long-lived attach findings in the spec.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
bzed and others added 4 commits November 21, 2026 23:55
… published repositories

The publish job needed arch-repo, so a failure of the best-effort Arch
build skipped the whole deploy, docs and apt repository included. publish
now runs when build, apt and rpm-repo succeeded; without a new pacman
repository it keeps the published one (Pages replaces the whole site).

verify-repos installs dzo from the published apt, dnf and pacman
repositories with the signatures enforced, after a deploy that published:
the CI install jobs only test their own package file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The deb job's test run hung ten minutes in TestSdNotify, in a datagram
write that its deadline did not interrupt. SdNotify now sends with
MSG_DONTWAIT on a non-blocking socket and retries a full queue for a
second; the test's abstract socket name is random (t.TempDir's base name
is 001 in every test process, and abstract names are shared by the
network namespace), and a new case checks that a listener that never
reads gives an error, not a hang.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
In the deb job's container a net.Conn write on a unix datagram socket
blocks in the kernel and ignores its deadline, so the queue-filling loop
of the new SdNotify case hung the run for ten minutes; it is the same
cause as the first hang, which SdNotify itself no longer has.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Rootless, `podman version` sets up the user namespace before it prints
and fails where that is not possible: the package-install jobs' unprivileged
containers (cannot clone: Operation not permitted) and a host whose dayz
user has no subuid range yet. `podman --version` prints the client version
without one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bzed
bzed merged commit a44945c into main Nov 21, 2026
39 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant