Linux Runtime Parity Validation

Swarm Hosts Linux support is validated by distro family and container runtime, not by a single happy-path lab host. This runbook defines the target matrix, the evidence format, and the checklist that child validation issues use before claiming Docker or Podman support on a distro family.

Issue #157 owns the framework and evidence format. Distro-family runtime proof belongs in the child issues:

  • 158: Ubuntu and Debian

  • 159: Fedora and RHEL-compatible distros such as Rocky Linux or AlmaLinux

  • 160: openSUSE and Arch-family rolling distros

  • 156: Podman runtime feature parity

Target Matrix

Distro target Docker Engine Podman rootful Podman rootless
Ubuntu LTS Verified in #179 / #158 Verified in #178 and tracked by #158 Conditional: implemented with rootless limitations; not a product-safe default without distro-specific rootless proof
Debian stable Verified in #179 / #158 Verified in #179 / #158 Conditional: implemented with rootless limitations; not a product-safe default without distro-specific rootless proof
Fedora Verified in #180 / #159 Verified in #159 after the #275 SELinux relabel fix Conditional verified in #159; not a default without rootless prerequisites
Rocky/Alma/RHEL-compatible Verified in #180 / #159 Verified on Rocky Linux in #159 after the #275 SELinux relabel fix Conditional verified on Rocky Linux in #159; not a default without rootless prerequisites
openSUSE Unverified target, #160 Unverified target, #156 and #160 Conditional unverified target, #156 and #160
Arch/Manjaro rolling Unverified target, #160 Unverified target, #156 and #160 Conditional unverified target, #156 and #160

Podman entries stay unverified until a distro-specific live run proves that the agent can drive the selected Podman mode with the same deployment, logs, cleanup, Minecraft status, and RCON behavior as the Docker path. Rootless Podman is conditional because it depends on subordinate UID/GID ranges, rootless networking, high host ports, and user-service survival.

Fedora and RHEL-Compatible Docker Prerequisites

  • Fedora 44 + Docker proof in #159 and #180 used Docker Engine 29.6.1 with SELinux enforcing and firewalld inactive.
  • Rocky 10.2 + Docker proof in #159 and #180 used Docker Engine 29.6.1 with firewalld inactive.
  • Rocky Linux live validation required a kernel refresh to the 6.12.0-211.26.1.el10_2.x86_64 line before Docker bridge networking could complete reliably.

Fedora and RHEL-Compatible Podman Prerequisites

  • Fedora 44 and Rocky 10.2 rootful Podman proof in #159 used the production agent from #275. That fix adds SELinux relabeling to Linux Podman deployment data bind mounts so the Minecraft container can write /data on enforcing hosts.
  • Fedora 44 and Rocky 10.2 rootless Podman proof in #159 used high host port ranges, valid subordinate UID/GID mappings, and normal user-owned install and data roots under /home/dillon.
  • On Fedora/RHEL validation hosts with Docker and Podman installed together, Docker's iptables FORWARD policy can block Podman bridge egress and published-port DNAT. Before a Podman live run, verify a Podman container can resolve DNS, reach the internet, and answer through a published high TCP port. The #159 disposable VMs required temporary podman0 forwarding allow rules before Minecraft metadata downloads and relay status probes succeeded.
  • Rootless Podman can create files owned by the user's subordinate UID range. The live validation driver removes disposable validation data with podman unshare rm -rf after plain rm -rf so cleanup works without escalating beyond the rootless Podman user namespace.

Debian-Family Podman Prerequisites

  • Ubuntu 24.04 rootful Podman proof in #156 and #178 used Podman 4.9.3 with crun, systemd cgroups, overlay storage, and a static LAN Hyper-V guest.
  • Debian 13 rootful Podman proof in #158 and #179 used Podman 5.4.2 with crun, systemd cgroups, overlay storage, and a static LAN Hyper-V guest.
  • On a Debian validation host with Docker and Podman installed together, Docker's nftables/iptables FORWARD policy can block Podman bridge egress. Before a Podman live run, verify an unprivileged container can resolve DNS and reach the internet through the selected Podman network. The #158 disposable Debian VM required a host forwarding-policy correction before Minecraft version metadata downloads succeeded inside the Podman container.

For issue #160, the agent validation workforce also exposes a focused opensuse-arch profile. Dispatch agent-validation-workforce with matrix_profile=opensuse-arch to plan the openSUSE and Arch-family rows together, or use target_filter for one row such as linux-opensuse-docker.

For issue #159, dispatch agent-validation-workforce with matrix_profile=fedora-rhel to plan the Fedora and Rocky/Alma/RHEL-compatible rows together. Use target_filter for one row such as linux-fedora-podman-rootful while iterating on a disposable validation VM.

Validation Runner

Print the built-in matrix:

scripts/validation/linux_runtime_matrix.py matrix
scripts/validation/linux_runtime_matrix.py matrix --format json

Generate a target-specific runbook:

scripts/validation/linux_runtime_matrix.py runbook --distro ubuntu-lts --runtime docker

Run a local preflight:

scripts/validation/linux_runtime_matrix.py preflight \
  --distro auto \
  --runtime docker \
  --artifact-dir /tmp/swarmhosts-linux-runtime-matrix

Run preflight through SSH against a validation VM:

scripts/validation/linux_runtime_matrix.py preflight \
  --distro ubuntu-lts \
  --runtime docker \
  --ssh-target dillon@192.0.2.10 \
  --ssh-key ~/.ssh/codex_swarm_test \
  --artifact-dir /tmp/swarmhosts-linux-runtime-matrix

The preflight checks only safe host facts and runtime prerequisites. It does not register agents, launch customer deployments, print environment variables, or copy secrets. The generated JSON and Markdown artifacts include a hashed host identity, OS/runtime facts, prerequisite status, and a live validation checklist.

Live Validation Checklist

For each distro/runtime child issue, record proof for:

  1. Agent install or update path completed.
  2. Agent registration and identity persistence verified.
  3. Deployment create/start/stop/restart/delete lifecycle verified.
  4. Minecraft Java status protocol reachable through the user-facing endpoint.
  5. RCON or game-command delivery verified.
  6. Deployment logs visible and sanitized.
  7. Deployment cleanup removed containers and data created by the run.
  8. Deployment and host support reports are safe to paste.

For Minecraft, the status check must use the actual Minecraft Java status protocol through the user-facing endpoint. TCP reachability alone is not enough.

Recording Evidence

After live validation, record a sanitized artifact:

scripts/validation/linux_runtime_matrix.py record \
  --distro ubuntu-lts \
  --runtime docker \
  --preflight-json /tmp/swarmhosts-linux-runtime-matrix/latest.json \
  --install pass \
  --registration pass \
  --deployment-lifecycle pass \
  --minecraft-status pass \
  --rcon pass \
  --logs pass \
  --cleanup pass \
  --support-report pass \
  --artifact-dir /tmp/swarmhosts-linux-runtime-matrix

Use warning, blocked, fail, skipped, or not_run when a step is not a clean pass. Add a short detail after a colon:

scripts/validation/linux_runtime_matrix.py record \
  --distro fedora \
  --runtime podman-rootless \
  --minecraft-status blocked:"Podman rootless network path does not expose the relay backend yet" \
  --artifact-dir /tmp/swarmhosts-linux-runtime-matrix

The runner writes timestamped JSON and Markdown files plus latest.json and latest.md in the artifact directory. The Markdown output is safe to paste into the GitHub issue or PR after a final human scan.

Unsupported or Blocked Combinations

If validation finds a real unsupported combination, create a follow-up issue instead of silently leaving the matrix ambiguous. Include:

  • distro target and runtime mode;
  • preflight artifact summary;
  • failing checklist step;
  • exact user impact;
  • whether the fix belongs in agent runtime support, docs, installer/bootstrap, relay networking, Minecraft/RCON behavior, logs, cleanup, or support reports.

Use status:ready, agent:skitter, parallel:safe unless the work touches runtime behavior directly; runtime implementation work should be serialized.