felhom-agent/REPORT.md

REPORT — agent v0.20.0: golden stacks-dir bind + per-guest hostname/CT + bake base-infra images (2026-06-11)

Repo: felhom-agent · Version: 0.20.0 · Date: 2026-06-11 Pushed commit: 1799fcd · paired with felhom-controller v0.41.0 (abbd948) + golden rebake.

What shipped (all in configs/build-golden.sh + the provision path; no change to proxmox/authz/token fences)

• Section-G mount fix (load-bearing): the in-guest controller writes app/infra compose stacks under /opt/docker/stacks inside its container, but the baked controller-bootstrap docker run never bind-mounted that path — so docker compose up (run by the GUEST daemon over the shared socket) resolved every relative bind source on the guest filesystem, silently creating empty dirs and breaking every bind-mounted stack (base infra AND customer apps). The bootstrap unit now mkdir -p /opt/docker/stacks and adds a same-path host bind -v /opt/docker/stacks:/opt/docker/stacks (a named volume would NOT fix this). Empirically confirmed on guest 9201 before writing the fix.
• Per-guest container hostname (3A): the bootstrap unit parses customer.id from /etc/felhom-bootstrap/bootstrap.json with a portable sed (NO jq in the golden) and passes --hostname <customer-id> to docker run. Security-hardened (flagged by the commit security review): the id is validated to a DNS-safe label (reject spaces/slashes/leading-dash) and passed via a quoted array, so a malformed/hostile id can't smuggle docker flags (e.g. --privileged) into the de-privileged run. Empty/invalid → no --hostname (fail-safe).
• Per-guest CT/LXC name (3B): --selftest=provision defaults -hostname to the DNS-safe-sanitized -customer-id when not given, so the bring-up's existing SetConfig hostname step names the CT meaningfully instead of inheriting the golden's felhom-golden. New sanitizeHostname (lowercase, collapse invalid → -, trim, ≤63).
• Bake base-infra images: the golden pulls the three PINNED, PUBLIC base-infra images (traefik:v3.6.7, cloudflare/cloudflared:2026.6.0, gtstef/filebrowser:1.3.3-stable) into its Docker storage so the controller's first-boot bring-up is OFFLINE-capable. A docker manifest inspect hard gate fails the bake early on a bad pin. Tags MUST match the controller's internal/infra constants.

Live validation (demo host felhom-pve / PVE 9.2.2)

• Agent v0.20.0 built (go1.26, ldflags -X main.version=0.20.0) and deployed to /usr/local/bin/felhom-agent; service active.
• Golden rebaked → local:backup/vzdump-lxc-9100-2026_06_11-15_06_05.tar.zst (877 MB, up from ~599 MB ≈ the three baked infra images). Controller :0.41.0 pulled (digest 0a9d456…) + all 3 infra pins resolved past the hard gate. /etc/felhom-controller-image reads :0.41.0.
• Guest 9201 destroyed + re-provisioned from the new golden: provision header hostname=demo-felhom; CT config hostname: demo-felhom; runtime hostname demo-felhom; controller os.Hostname() = demo-felhom. Back-half minted the per-guest token + attached the mp9 bootstrap mount.
• After pct reboot + systemctl restart felhom-agent: the baked controller-bootstrap deployed the controller, which pulled its config and stood up the base stack — 4 containers running, Health = OK, cloudflared tunnel registered, the /opt/docker/stacks bind resolving end-to-end.

Notes

• The registry credential used for the bake was staged transiently as a 0600 file on the host and removed by the rebake; it is stored out-of-band and never committed.