docs: fix the wrong journalctl scope and document the host-network port drop

**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) <noreply@anthropic.com>
This commit is contained in:
archipelago
2026-08-08 03:50:15 -04:00
co-authored by Claude Opus 5
parent 623eb0f033
commit ecd9295e96
2 changed files with 10 additions and 5 deletions
+5 -5
View File
@@ -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
+5
View File
@@ -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