M1b — Brain brings up the control-plane stack (Caddy + malmo-ui + socket-proxy)

[onel]

Size: L · Area: backend · Depends on: #164 · Part of #161

Net-new brain code: today the brain only configures Caddy via the admin API — it never launches it (dev runs Caddy standalone; dev/docker-compose.yml says so). Production requires the brain to bring up Caddy, malmo-ui, and the docker-socket-proxy on startup. Carries the second spec-collision risk (socket-proxy vs. compose CLI).

Spec / source of truth: CONTROL_PLANE.md # Locked: Caddy is malmo substrate / # Locked: the dashboard UI is a brain-launched container / # Locked: Docker socket exposure mitigated by socket proxy

Do:

• On brain startup, reconcile the control-plane stack from the M0 compose (Caddy + malmo-ui + socket-proxy), the same way lifecycle.Reconcile handles app containers.
• Ensure the malmo Docker network exists before the stack comes up (in dev it's an external network the compose assumes; on a real box something must create it).
• Reach Caddy's admin API by service name (http://malmo-caddy:2019), not localhost:2019 — the natively-run dev brain uses localhost; a containerized brain cannot. Audit internal/caddy/ for the hardcoded endpoint.
• Stand up tecnativa/docker-socket-proxy and switch the brain to DOCKER_HOST=tcp://docker-proxy:2375.
• Validate the socket-proxy ↔ compose-CLI integration (open risk): confirm docker compose works through the proxy allowlist; if endpoint families are insufficient, widen the allowlist or escalate — a CONTROL_PLANE.md # Locked: Docker socket exposure revisit + a DECISIONS.md entry.

Touch: internal/lifecycle/, cmd/brain/, the control-plane compose, internal/caddy/.

Done when: booting the VM yields Caddy + malmo-ui + socket-proxy all launched by the brain; the dashboard SPA loads through Caddy; the brain reaches Docker only via the proxy (raw socket not mounted). The socket-proxy validation outcome is recorded.

[bogdanpydev]

M1b socket-proxy ↔ compose-CLI validation — findings + a decision for @onel

Reassigning to you: this issue's "second spec-collision risk (socket-proxy vs. compose CLI)" is real and needs an architecture call before M1b can land. Validation run against local Docker (29.5.3, compose v2.40.3), reproducing the production topology — tecnativa/docker-socket-proxy on malmo-ingress with M0's exact allowlist, a containerized docker:28-cli driving compose via DOCKER_HOST=tcp://proxy:2375. Recorded in docs/progress/socket-proxy-compose-validation.md (PR #178, stacked on #164).

✅ Finding 1 — the compose path is fully proxy-compatible

docker compose up -d and down -v both work end-to-end through the proxy: create/start/stop/delete, external malmo-ingress attach, ports, restart: unless-stopped, bind mount, read_only+tmpfs. The DELETE path (the brain's compose down -v uninstall) is covered by the proxy's POST=1. M0's allowlist needs no widening for compose. Also confirmed: a containerized client's bind mounts only resolve when the project dir is at an identical host/container path (the daemon resolves bind sources as host paths) → stage the control-plane compose + caddy.json under /var/lib/malmo/control-plane/, already mounted same-path per #164.

⚠️ Finding 2 — docker exec is denied, which breaks managed-DB provisioning (the decision)

The proxy denies EXEC by design (CONTROL_PLANE.md # Docker socket exposure). But internal/lifecycle/services.go provisions managed Postgres/MySQL/MariaDB via docker exec — provisionPostgresDB (psql CREATE ROLE/DATABASE), provisionMySQLDB (mysql -e), dropServiceGrants on uninstall, waitServiceReady (pg_isready/mysqladmin). The instant M1b sets DOCKER_HOST=tcp://docker-proxy:2375, all of these fail — and #159 (managed Redis) is in flight on the same seam. Dev is unaffected (the native dev brain keeps the raw socket); only the containerized/production brain switches.

Three resolutions — I won't pick unilaterally since one flips a Locked security decision:

1. Widen to EXEC=1 — unblocks managed DB but lets a compromised brain exec into any container (the exact threat the proxy exists to stop). Needs a DECISIONS.md flip + threat-model revisit.
2. Re-architect provisioning off docker exec — TCP client, or a one-shot provisioning sidecar. Correct end state; spans SERVICE_PROVISIONING.md; its own L/XL issue.
3. Defer — ship the proxy switch (correct prod security), keep EXEC denied, gate managed-DB-in-production on the re-architecture (managed DB is pre-production regardless).

Already settled

• Proxy-bootstrap chicken-and-egg (brain can't up its own only Docker path) → host-agent seeds the proxy + malmo-ingress; the brain owns Caddy + malmo-ui and reaches Docker only via the proxy. Refines CONTROL_PLANE.md # the dashboard UI is a brain-launched container (DECISIONS.md entry lands with implementation).
• Caddy "audit" → no hardcoded endpoint; injected via caddy.New(cfg.caddyAdmin), prod just sets MALMO_CADDY_ADMIN=http://malmo-caddy:2019.

M1b implementation is ready to proceed once Finding 2 is settled.