mosaicstack/stack
20
0
Fork 1
Code Issues 335 Pull Requests 14 Actions Packages Projects Releases 15 Wiki Activity

docs: containerization plan + PRD D15 (tiered deployment, standalone v1 bar) #1484

Merged
marcie merged 4 commits from docs/containerization-plan into next 2026-08-30 05:21:43 +00:00
Conversation 0 Commits 4 Files Changed 2
+133 -17
2 changed files with 133 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PRD.md
+34 -17
View File
@@ -197,24 +197,41 @@ conflict must amend one of them explicitly, never fork a third document
- A second writable task store beside PostgreSQL (native-kanban-sot invariants).
- Fully-designed federation in v1 (D3 — roadmap placeholder only).
### 12. Decision registry
### D15 — Tiered containerized deployment (2026-08-30, containerization lane)
| ID | Decision (short form) |
| --- | ------------------------------------------------------------------------------------------------------------------ |
| D1 | Open-source, AI-first, self-hosted platform for agentic management + life OS |
| D2 | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC |
| D3 | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred |
| D4 | Re-runnable, extensible, per-mode onboarding wizards |
| D5 | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT |
| D6 | Only product-relevant material migrates from brains; operational records stay and link |
| D7 | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25) |
| D8 | webUI sits over official framework tooling; CLI primary |
| D9 | Not a hosted business; company = organizational separation for one operator |
| D10 | better-auth is the account system of record; external IdPs via OIDC |
| D11 | Small v1 slice; ALL phases on the documented roadmap from day one |
| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first |
| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten |
| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers |
The stack ships a tiered deployment target, additive to the architecture
gate (D8): (1) Standalone tier — docker compose is the canonical
single-host deployment: postgres, valkey, openbao, gateway, appservice
and the served webUI in one composition, with migrations, health checks,
and a documented install/upgrade path; the registry (CI-published
images) is the only deployment source. (2) Enterprise tier — Kubernetes
manifests for the same service set, phase-gated on the standalone tier
holding its acceptance bar. The v1 acceptance bar for the standalone
tier: compose-up healthy; webUI hosts agent chat; an in-stack agent can
open a PR to this repo; CI validates it; the running deployment adopts
the merged change (pull + restart). Federation (D3 clause) remains
deferred and unforeclosed. Implementation plan:
docs/plans/2026-08-30_containerization.md.
## 12. Decision registry
| ID | Decision (short form) |
| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| D1 | Open-source, AI-first, self-hosted platform for agentic management + life OS |
| D2 | Hierarchy company→estate→project→workspace→kanban; bubble-up; granular RBAC |
| D3 | Standalone vs Enterprise; one-way conversion; per-user brains + Vault required in Enterprise; federation deferred |
| D4 | Re-runnable, extensible, per-mode onboarding wizards |
| D5 | North star = this rewrite of docs/PRD.md; stack docs/ = product SSOT |
| D6 | Only product-relevant material migrates from brains; operational records stay and link |
| D7 | Spec-inventory sweep launched immediately (executed; INPUTS baseline frozen by operator ruling T2, 2026-08-25) |
| D8 | webUI sits over official framework tooling; CLI primary |
| D9 | Not a hosted business; company = organizational separation for one operator |
| D10 | better-auth is the account system of record; external IdPs via OIDC |
| D11 | Small v1 slice; ALL phases on the documented roadmap from day one |
| D12 | HARD RULE: webUI never bypasses tooling; missing tool ⇒ build the tool first |
| D13 | workspace_id stays the hard isolation unit; hierarchy is parent structure above; kanban SOT amended, not rewritten |
| D14 | Sensitive profile data in the user's own brain only; postgres holds structure/consent/pointers |
| D15 | Tiered containerized deployment: compose standalone tier (five-point v1 bar) + phase-gated k8s enterprise tier; registry-only image source | 2026-08-30 containerization lane; plan docs/plans/2026-08-30_containerization.md |
The full decision texts are recorded in the operator decision log (USC estate
brain, webui-audit lane, `GRILL.md`).
docs/plans/2026-08-30_containerization.md
+99
View File
@@ -0,0 +1,99 @@
# 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).