From ecd9295e96029a0e4fdfa655ec5733a5e3aca164 Mon Sep 17 00:00:00 2001 From: archipelago Date: Sat, 8 Aug 2026 03:50:15 -0400 Subject: [PATCH] docs: fix the wrong journalctl scope and document the host-network port drop MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit **container-lifecycle.md** told operators to read the reconciler's decisions with `journalctl --user -u archipelago`. That returns nothing: `archipelago.service` is a SYSTEM unit (`WantedBy=multi-user.target`) that merely runs as `User=archipelago`. It's `sudo journalctl -u archipelago`. Easy to get wrong because the companion Quadlet units next door genuinely are `--user`, so both forms appear in the docs and only one is right per unit — spelled that out inline. Swept the rest of docs/: no other instance. **quadlet-compilation.md** — added the `Network=host` case. Podman rejects `PublishPort` with host networking (crash-loop, exit 125), so the renderer drops declared ports rather than emitting them (`render_host_network_omits_publish_ports`). A developer reading the directive list would otherwise expect a mapping that never appears. Everything else in both docs verified against quadlet.rs / prod_orchestrator.rs / boot_reconciler.rs: the unit dir, the DO-NOT-EDIT header, Pull=never, DropCapability=ALL, Secret=…,type=env, TimeoutStartSec=0, RestartSec=10, WantedBy=default.target, the render/write_if_changed/enable_now/disable_remove four-step, uid 1000, adopt_existing, the user-stopped.json / user-uninstalled.json desired-state gates, and the 30s tick. Co-Authored-By: Claude Opus 5 (1M context) --- docs/container-lifecycle.md | 10 +++++----- docs/quadlet-compilation.md | 5 +++++ 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/container-lifecycle.md b/docs/container-lifecycle.md index 2e04b7cc..f3b6c3b9 100644 --- a/docs/container-lifecycle.md +++ b/docs/container-lifecycle.md @@ -87,18 +87,18 @@ from under the operator by the catalog. ## Inspecting lifecycle state -Run as the archipelago service user: - ```bash -# what podman actually has +# what podman actually has — run as the archipelago service user (rootless) podman ps -a --format '{{.Names}}\t{{.Status}}' # the durable desired-state signals cat /var/lib/archipelago/user-stopped.json cat /var/lib/archipelago/user-uninstalled.json -# the reconciler's decisions -journalctl --user -u archipelago | grep -iE 'reconcile|adopt|install|user.stopped' +# the reconciler's decisions. archipelago.service is a SYSTEM unit that runs +# as User=archipelago (WantedBy=multi-user.target), so this is not --user — +# unlike the companion Quadlet units, which are per-user. +sudo journalctl -u archipelago | grep -iE 'reconcile|adopt|install|user.stopped' ``` ## Related diff --git a/docs/quadlet-compilation.md b/docs/quadlet-compilation.md index 1d79872a..a98aa486 100644 --- a/docs/quadlet-compilation.md +++ b/docs/quadlet-compilation.md @@ -65,6 +65,11 @@ Two things to note in that mapping: - **`Pull=never` is deliberate.** The provisioner does not pull images from here; the image must already be local (pre-pulled or built). A missing image surfaces immediately instead of retrying silently behind systemd's restart loop. +- **`PublishPort` is dropped entirely under `Network=host`.** Podman rejects the + combination and the container crash-loops on exit 125, so declared ports are + omitted rather than rendered. With host networking the container is already on + the host's ports; a manifest that declares both is not an error, the mapping is + just silently unnecessary. ## Where units land