Plan — Stack Containerization (tiered deployment)

Status: DRAFT for review. Charter: fleet/lanes/stack-containerization (brain) NORTH-STAR.md; PRD amendment in the same PR adds D15. Supersedes nothing; sequences the absorbed M4 remainder per its lane.

Measured baseline (origin/next @ `143ba0f5`, 2026-08-30)

docker-compose.yml: dev infrastructure only — postgres (pgvector), valkey, otel-collector, jaeger. No application services.
docker-compose.federated.yml: standalone overlay for the FEDERATED storage tier (own postgres/valkey; port-conflicts the base stack by design). Not an app deployment.
docker/gateway.Dockerfile, docker/appservice.Dockerfile: multi-stage production builds (node:22-alpine) EXIST; the gateway image includes the web SPA bundle (#1444).
CI (publish.yml) builds and publishes these images (next-channel prereleases + main stable), and runs verify:release fail-closed.
Gap: no stack-level composition wires gateway+appservice+data plane into one deployable unit; no blessed install/upgrade path; no in-container agent-runtime story for the dogfood loop.

Target (PRD D15 amendment)

Tiered deployment, additive to the existing architecture:

Standalone tier (v1 bar): docker compose up on one host brings postgres, valkey, openbao, gateway, appservice (and the webUI the gateway serves) to healthy; migrations apply; the webUI hosts agent chat; an in-stack agent can read this repo and open a PR; CI validates; the deployment adopts merged images (pull + restart).
Enterprise tier (post-v1): Kubernetes manifests (or Helm) for the same service set, phase-gated on the standalone bar holding.

Phases

Phase A — blessed standalone compose

A1 Compose service definitions for gateway + appservice joining the existing infra compose (profiles: dev keeps today's behavior; stack adds the app tier), with health checks and dependency order.
A2 Migrations on boot (or an explicit migrate step) with idempotency and version pinning; init-db.sql folded into pg-init.
A3 Openbao in the compose set (secret plumbing for the app tier).
A4 .env.example + mosaic.config.json defaults documented for the standalone mode; mode recorded per the mode-conversion contract.
A5 Smoke: docker compose --profile stack up green on a scratch host; webUI served; agent chat reachable; failures catalogued and fixed.
Acceptance: the five-point NORTH-STAR bar measured live.

Phase B — component completion

Decompose JIT from A5's catalogue. Known candidates: agent runtime bits (brain/tool access paths in-container), repo credentials for the dogfood agent, watch/comms surfaces inside the deployment.

Phase C — CI/CD parity

Publish pipeline is the only image source (already true); add the deployment-side pull/upgrade path (compose pull + migrate + restart = next iteration); document the promotion flow next -> registry -> deployment.

Phase D — coordinator integration (GATED)

Blocked until the guides-proposed control-plane refactor lands; then wire mosaic coord service lifecycle per that design.

Phase E — enterprise tier

k8s manifests/Helm for the same set; phase-gated on Phase A holding.

Absorbed M4 remainder

M4-3 pivot: KBN-101 foundation first (per ruling R6), then expand DDL.
M4-5: lands inside Phase B/C where natural.
M4-6 (composes M4-1+M4-4): last, as designed.

Non-goals (v1)

No Kubernetes in v1; no multi-host federation; no replacement of the fleet's brain-based seats (the stack is an additional operator surface); no on-host image builds for deployment (registry only).

3.6 KiB Raw Blame History