Files

T

CI / check (push) Successful in 36s

Details

feat(deploy): Komodo fleet deployment — resources.toml + decision

Adopt Komodo Periphery (over the NetBird mesh) as the booth fleet control plane,
superseding SSH-and-booth.sh. The booth runs the SAME compose files; Komodo Core
drives them remotely. booth.sh is demoted to a break-glass local fallback.

- komodo/resources.toml mirrors the working park-buzi Stack (built by hand in the
  Core UI, then exported to TOML — field names match the running v2.2). Stack-only:
  servers are created by the agent onboarding OUTBOUND (one-time onboarding key →
  Periphery self-registers, auto-rotating keys, booth opens no inbound port), so
  there is no [[server]] block. Per-booth secrets via [[...]] refs to Core's store.
- komodo/README.md + .env.komodo.example document the flow and the hard rules
  (no webhook; onboarding/outbound/mesh-only; per-booth unique secrets; never
  down -v the ledger volume).
- wiki/decisions/fleet-deployment-komodo.md records the decision + threat-model
  analysis (Periphery is a root agent → mesh-bound; EVENT_SIGNING_KEY-in-Core is a
  fraud-root blast radius until ATECC608 signs; Core is now Tier-0; GPL-3.0 is fine
  as external ops tooling). container-deployment reframed (booth.sh = fallback);
  index + log updated.

Verified end-to-end against a real booth (park-buzi): onboarded OK, Stack deployed,
all containers green, admin seeded.

Claude-Session: https://claude.ai/code/session_01Xcm6ikLgGoCxxHrxtjkk5V

2026-06-27 12:14:04 +02:00

3.7 KiB

Raw Blame History

`komodo/` — fleet deployment as code

Infra-as-code for the Komodo Core control plane that deploys the parking appliance to the booth fleet over the NetBird mesh. See wiki/decisions/fleet-deployment-komodo.md for the rationale, threat-model analysis, and the three settled choices (many/growing fleet · deploys are manual + pinned · secrets are Komodo-managed, per-booth).

This directory does not change how images are built or how the app runs — it's only the control plane. The booth still runs the same docker-compose.yml + docker-compose.prod.yml (container-deployment); Komodo just drives them remotely instead of someone SSH-ing in to run booth.sh.

Files

resources.toml — the Komodo resource definitions (Servers, Stacks, optional Builders/ Procedures), synced into Core via a ResourceSync. This is the reviewable, version- controlled source of truth for which booth runs what.
.env.komodo.example — the variables a Stack expects, documenting what comes from Core's secret store (per-booth JWT_SECRET / EVENT_SIGNING_KEY) vs. plain Stack env.

How Core consumes this (one-time)

In Komodo Core, create a ResourceSync pointing at this repo + path (komodo/resources.toml), on the branch you manage from (e.g. main). Core reads the file and reconciles Servers/Stacks to match. Thereafter, a PR to this directory + a sync is how you change the fleet — no clicking.

Komodo's TOML schema evolves across releases. Treat resources.toml as a starting sketch: resources.toml mirrors the working park-buzi Stack (built by hand in the Core UI, then exported to TOML — so field names match the running Komodo version, v2.2). Import it into the sync Unmanaged first and review the diff; it should be ~empty against the live Stack.

How servers get created — NOT here

There is no [[server]] block in resources.toml. Servers are created by the Periphery agent onboarding outbound: in Core, create a one-time Onboarding Key (Settings → Onboarding), then install Periphery on the booth passing --onboarding-key + --core-address (Core's reverse-proxy URL, reached over the NetBird mesh) + --connect-as=<booth-name>. The agent self-registers, generates its own auto-rotating key pair (private key never leaves the booth), and connects outbound — the booth opens no inbound port. The sync owns only the Stack, which references the server by the name it onboarded as (server = "park-buzi"). See wiki/decisions/fleet-deployment-komodo.md.

Adding booth N

Copy the [[stack]] block, change name, server (its onboarded name), and the per-booth secret references ([[park_<site>_jwt_secret]], [[park_<site>_event_signing_key]]). Create those secrets in Core's store first.

Hard rules encoded here (do not relax without updating the decision page)

No deploy webhook on a booth Stack. Deploys are a human action; pin TAG=dev-<sha> before a production booth goes live. A moving :dev on a production booth is the non-determinism we rejected. (TAG=dev here is fine while staging.)
Onboarding, outbound, mesh-only. Servers self-register via an onboarding key; Periphery connects outbound to Core's mesh URL and exposes no inbound port. Never a LAN/WAN address.
Secrets are per-booth and unique. EVENT_SIGNING_KEY signs the anti-fraud ledger — one leak must taint one booth, never the fleet. Reference Core secrets by name; never inline a real value in this file (it's in git).
Volumes preserved. The Stack must never run compose down -v — that would wipe the parking-data volume (the signed ledger). Komodo's "destroy" is gated for the same reason.

3.7 KiB Raw Blame History

komodo/ — fleet deployment as code