felhom.eu/REPORT.md

felhom.eu — task reports

Overwrite this file with a summary of the most recent task only (uniform with the other repos; not cumulative). The cumulative hub history lives in hub/CHANGELOG.md.

BUNDLE slice — Day-0 artifact manifest + self-install the agent (2026-06-28)

Hub v0.15.0 → v0.16.0 @ 39ef64e/d5266ca · host-install v1.0.0 → v1.1.0 @ 30ecf73

The host-bootstrap script now installs the agent itself (the last manual Day-0 prerequisite is gone). It fetches the agent binary + golden from Gitea generic packages and verifies each artifact's sha256 against a hub-vouched manifest before installing/using it. The hub is the checksum trust root (a different root than Gitea, which only stores the bytes); the fetch credential is the git token already inside the customer's controller.yaml (config-retrieve) — no new credential.

Hub (v0.16.0)

• store.go: ArtifactManifest{agent,golden version+sha256} in the existing hub_settings table; Get/SetArtifactManifest + generic getSetting/setSetting.
• handler.go: GET /api/v1/artifacts/{customer_id} — auth mirrors handleConfigRetrieve (X-Retrieval-Password, 404-then-401, constant-time). Unset manifest → 200 with empty fields.
• configs.go + configs.html: operator UI "Day-0 artifacts" card (POST /configs/artifacts, semver + 64-hex validation). main.go: env-seed (ARTIFACT_AGENT_VERSION/…_SHA256/GOLDEN_…), empty-fields-only so a UI edit sticks (the operator UI is password-gated — same escape hatch as the Phase-2 floor).
• Tests (artifact_test.go): returned-verbatim / unset-empty / 401 / 404 / store partial round-trip.

host-install (v1.1.0)

• New step 5/8 agent-install: resolve manifest + git token → fetch binary → verify sha256 vs hub manifest (abort on mismatch) → install the non-root felhom-agent user + binary + sudoers (visudo -cf-validated) + canonical unit. Installs the sudo package (the non-root model needs it).
• New step 7/8 golden: local fallback else fetch+verify+import from Gitea (--force-gitea-golden).
• Agent now runs non-root (privileged.mode: "sudo"); config chowned to the service user.
• --skip-provision (agent-only install/verify), pre-flight relaxed (binary no longer required), README prerequisites trimmed to: install PVE + create the customer.

Green gate

Hub: go build/vet/test ./... green. Scripts: bash -n + shellcheck -S warning clean.

Deployed + live-proven (felhom-pve, demo-felhom)

• Hub 0.16.0 rolled out to k3s (felhom-system/hub); artifact manifest seeded via env. Endpoint live: correct passphrase returns the manifest; wrong/missing → 401, unknown customer → 404.
• Published agent 0.43.0 (sha 8b989917…) + golden 0.85.1 (sha f87031cc…) to Gitea generic.
• From-scratch agent install (live agent moved fully aside): fetch → verify sha256 → install (non-root user + binary + sudoers + unit + config) → service active as felhom-agent → --selftest=hub host-report landed → 9201 still managed. The git token (from controller.yaml) reads Gitea generic packages (confirmed PUT/GET/DELETE).
• sha256 negative: a corrupted published binary made the install abort ("Refusing to install — verify-before-use", exit 1); the good binary was then restored (sha re-verified).
• Golden fetch+verify+import from Gitea proven; the test-imported copy was cleaned up.

Two real bugs found + fixed live

1. The sudo package wasn't installed (the host ran the agent root+direct) — step 5 now installs it.
2. felhom-agent.sudoers had unescaped commas in the lvs/lsblk -o lists → visudo -cf rejected it (never validated live before). Fixed in felhom-agent (escaped commas).

Observations

• Throwaway full provision SKIPPED to protect the live demo: a guest provisioned with demo-felhom's config would fight the live 9201 for the Cloudflare tunnel/domain. The new code (agent install + golden fetch/verify/import) is fully proven; the golden→guest restore is unchanged from prior slices. Use a dedicated throwaway customer for an end-to-end provision proof.
• Non-root + PBS: the agent can't read /etc/pve/priv as felhom-agent (PBS datastores skipped with a WARN; cadence disabled on the demo). Needs a pmxcfs group/ACL or sudoers grant for PBS in production — follow-up.
• Per-customer artifact pinning is a future hook (the endpoint already takes the customer id; v0.16.0 returns the global current set).
• felhom-pve left with a healthy non-root agent 0.43.0 + 9201 managed; rollback bundle kept at /root/agent-backup-bundle-test.