serving: defaults.env header + Makefile + .gitignore + doc refs

Completes the rename commit (which carried only the file move): defaults.env
layering header, docker-compose usage comment, serving/Makefile (sets
COMPOSE_ENV_FILES), serving/.gitignore (.env), and the README/TODO references.

docs/TODO.md

@@ -1200,7 +1200,7 @@ write + **reboot converges** (2nd boot runs the secure path); (f) prod: broker o
 
 **TEMPORARY (2026-06-28): broker also added to the MAIN serving stack**
 (`serving/docker-compose.yml`, `enrol-broker` service + `ENROL_*` in
-`serving/.env.example`) so a single `compose up` in `serving/` brings the
+`serving/defaults.env`) so a single `compose up` in `serving/` brings the
 `/enrol/` endpoint up while the host side is built. Defaults to the
 zero-dependency lab path — **`mock` signer** (ephemeral CA; certs NOT trusted by
 RADIUS/NVMe) + **plaintext loopback admin** (`ENROL_ADMIN_INSECURE=true`). The

serving/.gitignore

@@ -0,0 +1,4 @@
+# Per-environment overrides + secrets. defaults.env (committed) holds the
+# defaults; .env is layered over it (COMPOSE_ENV_FILES=defaults.env,.env) and
+# holds only your per-LAN values + secrets — never commit it.
+.env

serving/Makefile

@@ -0,0 +1,45 @@
+# Makefile — convenience wrapper for the serving stack.
+#
+# Sets COMPOSE_ENV_FILES so `make up` / `make logs` / etc. layer the committed
+# defaults.env UNDER your .env overrides automatically — no need to export it or
+# pass --env-file. (Plain `docker compose …` still works if you export
+# COMPOSE_ENV_FILES=defaults.env,.env yourself.) Run from serving/.
+
+export COMPOSE_ENV_FILES := defaults.env,.env
+
+COMPOSE := docker compose
+SERVICE ?=
+
+.DEFAULT_GOAL := help
+
+.PHONY: help up down restart pull logs ps config
+
+help: ## Show this help
+	@grep -hE '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+	  | awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-12s\033[0m %s\n", $$1, $$2}'
+
+# .env must exist because COMPOSE_ENV_FILES lists it — guard with a clear message.
+.env:
+	@echo "ERROR: .env not found — create it with your per-LAN overrides (BOOT_IFACE / SERVER_IP / DHCP range / IMAGE_VERSION; see defaults.env)." >&2
+	@exit 1
+
+up: .env ## Start the stack (dnsmasq + http + nvmeof)
+	$(COMPOSE) up -d
+
+down: .env ## Stop + remove the stack
+	$(COMPOSE) down
+
+restart: .env ## Recreate a service (SERVICE=dnsmasq) or all
+	$(COMPOSE) up -d --force-recreate $(SERVICE)
+
+pull: .env ## Pull the CI-built images
+	$(COMPOSE) pull
+
+logs: .env ## Follow logs (SERVICE=dnsmasq for one)
+	$(COMPOSE) logs -f $(SERVICE)
+
+ps: .env ## Show container status
+	$(COMPOSE) ps
+
+config: .env ## Print the resolved (layered) compose config
+	$(COMPOSE) config

serving/README.md

@@ -43,10 +43,12 @@ Keep `nvmet_traddr` (UKI) == `NVME_HOST` (this stack's `.env`).
 
 ```bash
 cd serving
-cp .env.example .env      # edit IMAGE_VERSION, BOOT_IFACE, SERVER_IP, DHCP range
+# config = committed defaults.env + your .env overrides, layered (or use `make`):
+export COMPOSE_ENV_FILES=defaults.env,.env
+printf 'IMAGE_VERSION=<ver>\nBOOT_IFACE=<iface>\nSERVER_IP=<ip>\n' > .env   # + DHCP range
 docker login git.bitasylum.org
-docker compose up -d --build
-docker compose ps
+docker compose up -d --build      # or simply: make up
+docker compose ps                 # or: make ps
 ```
 
 `IMAGE_VERSION` must match the built tag (e.g. a branch build is

serving/defaults.env

@@ -1,4 +1,16 @@
-# Copy to .env and edit for your test LAN/bridge, then: docker compose up -d
+# defaults.env — the COMMITTED default configuration for the serving 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>
+#   # or just use the Makefile: `make up` / `make logs` (sets it for you)
+#
+# Then put ONLY per-environment overrides + secrets in .env (gitignored) — at
+# least BOOT_IFACE / SERVER_IP / DHCP range / IMAGE_VERSION for your LAN. Changing
+# a default here reaches every run without anyone re-copying it. (.env must exist
+# when COMPOSE_ENV_FILES lists it; create it with at least those overrides.)
 
 # Release being served. Must match the Packer build (fleet-<version>.efi).
 IMAGE_VERSION=0.0.0-2eefd97

serving/docker-compose.yml

@@ -29,8 +29,9 @@
 #     docker cp $id:/artifacts/. ./artifacts/$IMAGE_VERSION/; docker rm $id
 #   Private registry: docker login git.bitasylum.org first so the image pulls.
 #
-# Usage:
-#   cp .env.example .env   # then edit BOOT_IFACE / SERVER_IP / DHCP range
+# Usage (config = committed defaults.env + your .env overrides, layered):
+#   export COMPOSE_ENV_FILES=defaults.env,.env   # or use the Makefile (make up)
+#   printf 'BOOT_IFACE=...\nSERVER_IP=...\n' > .env   # per-LAN overrides + secrets
 #   docker compose up -d
 # =============================================================================