100 lines
4.6 KiB
Markdown
100 lines
4.6 KiB
Markdown
# 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:
|
|
|
|
1. **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).
|
|
2. **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
|
|
|
|
- Interface assumption (velma verdict A1, P5-RM-005/006): in-stack
|
|
dogfood agents inherit SEAT-GRADE identity — credential-slot
|
|
isolation, wrapper-first enforcement, no privileged coordination
|
|
identity, evidence by references that resolve outside the container
|
|
lifetime.
|
|
- 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)
|
|
|
|
- Gate (velma verdict C2): blocked until the checkpoint-and-lease child
|
|
of the guides-proposed control-plane refactor — core + WU-P1-CHECKPOINT
|
|
(schema, freshness, incarnation, clean-replacement resume; D57-D60
|
|
lineage) — carries an independent target-bound PASS. Wiring restarts
|
|
against the core alone re-creates the stale-incarnation failure class
|
|
D57-D60 closed. Transitive: inherits the T108 gates (P0 exit + Jason
|
|
P1 authorization).
|
|
- Scope (velma verdict C1): lifecycle actions (start/stop/restart/
|
|
health/recovery) executed by the SHIPPED coord client over the one
|
|
typed coordination contract (request id, actor identity, epoch,
|
|
revision, lease, correlation; typed stale rejection; worker role
|
|
boundary). No second coordination interface gets designed here —
|
|
containerization consumes the coordination contract, never defines it.
|
|
|
|
### 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).
|