fleet-manager: layer config as defaults.env (committed) + .env (overrides)

Rename .env.example -> defaults.env and make it the committed defaults layer. Compose reads defaults.env then .env (later wins) via COMPOSE_ENV_FILES, feeding BOTH container env and ${...} interpolation — so a changed default here reaches every run without re-copying, and .env shrinks to just overrides + secrets. No compose service restructure: the existing interpolated environment: blocks already build the container env; the layering just supplies their values from two files. (env_file: directive alone wouldn't work — it doesn't feed the image-tag / cross-service Influx / ACME_EMAIL interpolation this compose relies on.) Docs (DEPLOY §1, compose header, README) updated: export COMPOSE_ENV_FILES=defaults.env,.env, keep only secrets/overrides in .env.
2026-07-05 02:08:25 +00:00
parent 688ff1aa88
commit 45d7101472
4 changed files with 43 additions and 15 deletions
@@ -25,17 +25,29 @@ the architecture.

 ## 1. Configure

+Config is **layered**: `defaults.env` (committed defaults) + `.env` (your
+overrides + secrets, gitignored). Compose reads both — later wins — via
+`COMPOSE_ENV_FILES`, so a changed default in `defaults.env` reaches you without
+re-copying anything; `.env` stays small.
+
 ```bash
 cd serving/fleet-manager
-cp .env.example .env
-# Edit .env:
-#   FLEET_MGR_RP_ID / _ORIGIN   -> your UI hostname (diskless-server.bitasylum.org)
-#   FLEET_MGR_INFLUX_TOKEN      -> a long random secret (openssl rand -hex 32)
-#   INFLUX_ADMIN_PASSWORD       -> a strong password
+export COMPOSE_ENV_FILES=defaults.env,.env     # once per shell (or a Makefile/.envrc)
+# .env holds ONLY overrides + secrets — at minimum:
+cat > .env <<EOF
+FLEET_MGR_INFLUX_TOKEN=$(openssl rand -hex 32)
+INFLUX_ADMIN_PASSWORD=$(openssl rand -hex 24)
+ACME_EMAIL=you@bitasylum.org
+AWS_ACCESS_KEY_ID=...
+AWS_SECRET_ACCESS_KEY=...
+# override any other default from defaults.env here, e.g. FLEET_MGR_RP_ID=...
+EOF
 ```

-The Influx token is handed to **both** InfluxDB (its init admin token) and the
-manager, so one value wires them with no copy step. `.env` is gitignored.
+`COMPOSE_ENV_FILES` requires every listed file to exist, so create `.env` before
+running compose. Per-command alternative: `docker compose --env-file defaults.env
+--env-file .env …`. The Influx token is handed to **both** InfluxDB (its init
+admin token) and the manager, so one value wires them.

 ## 2. PKI

@@ -139,11 +139,13 @@ inventory for offline delivery. Metrics writing is behind a `MetricsSink`
 ## Deploy

 Full bring-up (PKI, Let's Encrypt DNS-01, `register-admin`, compose) is in
-[`DEPLOY.md`](DEPLOY.md). In short: `cp .env.example .env` → `./server-pki.sh` +
+[`DEPLOY.md`](DEPLOY.md). Config is layered: **`defaults.env`** (committed) +
+**`.env`** (overrides/secrets), via `COMPOSE_ENV_FILES=defaults.env,.env`. In
+short: set that + write your secrets to `.env` → `./server-pki.sh` +
 `../enrol-broker/admin-pki.sh … fleet-manager` → `docker compose up -d influxdb`
 → `docker compose run --rm fleet-manager register-admin <you>` → `docker compose
-up -d fleet-manager`. InfluxDB is private (published to loopback only); the
-manager uses host networking to reach the loopback broker + bind a routable
+up -d fleet-manager traefik`. InfluxDB is private (published to loopback only);
+the manager uses host networking to reach the loopback broker + bind a routable
 agent listener.

 ## Dev run
@@ -184,7 +186,7 @@ curl -s localhost:9500/api/hosts | jq '.hosts[] | {name:.identity.starship_name,
  (index + assets + API through the SPA origin).
 - **Checkpoint 7 (done):** deployment — three-stage `Dockerfile` (npm→dist→
  `go build -tags embedspa`→distroless), `docker-compose.yml` (private InfluxDB +
-  host-networked manager), `.env.example`, `server-pki.sh` (agent-plane fleet-CA
+  host-networked manager), `defaults.env`, `server-pki.sh` (agent-plane fleet-CA
  server cert), and [`DEPLOY.md`](DEPLOY.md) (PKI, LE DNS-01, `register-admin`
  bootstrap). Design docs updated (manager marked built; resolved transport/auth/
  metrics forks; per-host-versioning gap recorded).
@@ -1,5 +1,15 @@
-# Copy to .env and edit. See DEPLOY.md for the full bring-up.
-# .env is gitignored — it holds the Influx token and DB password.
+# defaults.env — the COMMITTED default configuration for the fleet-manager stack.
+#
+# Compose LAYERS this file, then .env (overrides), for both container env AND
+# ${...} interpolation. Enable the layering once per shell (later file wins):
+#
+#   export COMPOSE_ENV_FILES=defaults.env,.env
+#   # or per command:  docker compose --env-file defaults.env --env-file .env <cmd>
+#
+# Then put ONLY overrides + real secrets in .env (gitignored). Changing a default
+# here reaches every run without anyone re-copying it. The secret values below are
+# PLACEHOLDERS — override them in .env. (.env must exist when COMPOSE_ENV_FILES
+# lists it; create it with at least your secrets.)

 # --- WebAuthn RP (admin passkeys are ORIGIN-BOUND — must be the UI's real URL) --
 # The UI is fronted by Traefik on :443, so the origin is PORT-LESS.
@@ -2,12 +2,16 @@
 # fleet-manager — server-side fleet control plane + admin SPA, plus its private
 # InfluxDB metrics store. Runs on the MANAGEMENT host (never the boot LAN).
 #
-#   cp .env.example .env    # set RP origin, Influx token, cert/PKI paths
+#   export COMPOSE_ENV_FILES=defaults.env,.env   # layer defaults + your overrides
+#   printf 'FLEET_MGR_INFLUX_TOKEN=...\nINFLUX_ADMIN_PASSWORD=...\n' > .env  # secrets/overrides
 #   ./server-pki.sh         # issue the agent-plane server cert (fleet CA)
 #   ../enrol-broker/admin-pki.sh ../dot1x-bench/pki/broker fleet-manager
 #   docker compose up -d influxdb
 #   docker compose run --rm fleet-manager register-admin <you>   # passkey link
-#   docker compose up -d fleet-manager
+#   docker compose up -d fleet-manager traefik
+#
+# Config = defaults.env (committed) + .env (gitignored overrides), layered via
+# COMPOSE_ENV_FILES. Only put overrides + secrets in .env.
 #
 # See DEPLOY.md for the full bring-up (PKI, Let's Encrypt DNS-01, register-admin).
 #