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

docs(federation): operator setup + migration guides (FED-M1-11) #480

Merged
jason.woltje merged 1 commits from feat/federation-m1-docs into main 2026-04-20 02:07:17 +00:00
Conversation 0 Commits 1 Files Changed 4
+269 -1
jason.woltje commented 2026-04-20 02:07:05 +00:00
Owner
Copy Link
Copy Source

FED-M1-11 — Operator-facing documentation for the federated tier.

What ships

  • docs/federation/SETUP.md (NEW, 119 lines) — what federated is, prerequisites, docker compose start command, mosaic.config.json snippet, mosaic gateway doctor health check (with --json example), troubleshooting (port conflicts, pgvector errors, Valkey connection refused).
  • docs/guides/migrate-tier.md (NEW, 147 lines) — when to migrate, dry-run first, what gets migrated and what gets skipped (with rationale for accounts and provider_credentials being intentionally migrated as durable user-bound credentials), idempotency + advisory-lock semantics, manual verification queries, no in-place rollback.
  • README.md — 1-line blurb in existing Configuration section linking to both docs.

Constraints honored

  • Operator-actionable only; no design rationale (those live in PRD.md).
  • All commands verified against actual CLI surface in packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts.
  • Runbook NOT touched (deferred to FED-M7 per task spec).
  • No changes to MISSION-MANIFEST.md, MILESTONES.md, PRD.md.

Test plan

  • CI green (format/lint gates only — no code changes)
  • Manual: walk through SETUP.md against a fresh machine, then walk through migrate-tier.md against a seeded local tier

Refs #460

FED-M1-11 — Operator-facing documentation for the federated tier. ## What ships - `docs/federation/SETUP.md` (NEW, 119 lines) — what federated is, prerequisites, docker compose start command, mosaic.config.json snippet, mosaic gateway doctor health check (with --json example), troubleshooting (port conflicts, pgvector errors, Valkey connection refused). - `docs/guides/migrate-tier.md` (NEW, 147 lines) — when to migrate, dry-run first, what gets migrated and what gets skipped (with rationale for accounts and provider_credentials being intentionally migrated as durable user-bound credentials), idempotency + advisory-lock semantics, manual verification queries, no in-place rollback. - README.md — 1-line blurb in existing Configuration section linking to both docs. ## Constraints honored - Operator-actionable only; no design rationale (those live in PRD.md). - All commands verified against actual CLI surface in packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts. - Runbook NOT touched (deferred to FED-M7 per task spec). - No changes to MISSION-MANIFEST.md, MILESTONES.md, PRD.md. ## Test plan - [ ] CI green (format/lint gates only — no code changes) - [ ] Manual: walk through SETUP.md against a fresh machine, then walk through migrate-tier.md against a seeded local tier Refs #460
jason.woltje added 1 commit 2026-04-20 02:07:06 +00:00
docs(federation): operator setup + migration guides for federated tier (FED-M1-11)
ci/woodpecker/push/ci Pipeline was successful
Details
ci/woodpecker/pr/ci Pipeline was successful
Details
7493943945 
- docs/federation/SETUP.md (NEW, 119 lines): what federated is,
  prerequisites, docker compose start, config snippet, mosaic gateway
  doctor health check, troubleshooting (port conflicts, pgvector errors,
  Valkey connection)
- docs/guides/migrate-tier.md (NEW, 147 lines): when to migrate, dry-run
  first, what gets migrated/skipped (with rationale for accounts +
  provider_credentials), idempotency + advisory-lock semantics, manual
  verification queries, no in-place rollback
- README.md: 1-line blurb in Configuration section linking to both

All commands verified against actual CLI surface in
packages/storage/src/cli.ts and packages/mosaic/src/commands/gateway-doctor.ts.

Refs #460
jason.woltje merged commit 78841f228a into main 2026-04-20 02:07:17 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#480