f1fbe0e29a
Archived 4 completed OpenSpec changes (2026-04-02): - phase-3-enterprise (100/100 tasks) — 6 Phase 3 capabilities synced - devops-documentation (48/48 tasks) — 3 new + 1 merged capability - bedroom-developer-docs (33/33 tasks) — 4 new capabilities synced - engineering-docs (superseded by 2026-03-29 archive) — no tasks Main spec library grows from 21 → 35 capabilities (+14 new): federation, multi-tenancy, oidc, soc2, w3c-dids, webhooks, database, operations, system-overview, api-reference, core-concepts, developer-guides, quick-start + deployment (merged additive requirements) Active changes: 0 — project board is clear for Phase 4 planning. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
49 lines
2.2 KiB
Markdown
49 lines
2.2 KiB
Markdown
## Context
|
|
|
|
Phase 1 MVP is complete and live on `develop`. The bedroom developer docs cover the API surface. DevOps engineers — responsible for deployment, configuration, and operations — have no documentation. This gap creates operational risk: misconfigured environment variables, missed migration steps, and no recovery path when services fail.
|
|
|
|
**Audience**: Engineers who deploy and operate the AgentIdP infrastructure. Assumed knowledge: Linux shell, Docker, PostgreSQL basics, Node.js process management.
|
|
|
|
**Constraints:**
|
|
- Markdown only — renders on GitHub, no build step
|
|
- All commands are exact and runnable — no placeholders
|
|
- Honest about Phase 1 P1 gaps: Dockerfile does not exist yet; document what works now and mark pending items clearly
|
|
- Files live in `docs/devops/` — separate from `docs/developers/`
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- DevOps engineer can stand up a working local environment from scratch using only these docs
|
|
- Every environment variable is documented with type, requirement, and example
|
|
- Database schema and migration procedure are fully documented
|
|
- Security setup (JWT keys, CORS, secrets) is step-by-step
|
|
- Operations runbook covers the most likely failure scenarios
|
|
|
|
**Non-Goals:**
|
|
- Container deployment guide (Dockerfile is Phase 1 P1 — not built yet)
|
|
- Cloud/Kubernetes deployment (Phase 2)
|
|
- Monitoring/alerting setup (Phase 2)
|
|
- Multi-region or HA configuration (Phase 2)
|
|
|
|
## Decisions
|
|
|
|
**Decision 1: Separate folder vs subdirectory of docs/developers/**
|
|
Chosen: `docs/devops/` as a peer of `docs/developers/`.
|
|
Reason: Different audiences, no shared content, prevents confusion.
|
|
|
|
**Decision 2: Mark Dockerfile gap explicitly**
|
|
Chosen: `local-development.md` documents working `docker-compose` + `npm` path; `Dockerfile` noted as Phase 1 P1 pending with a placeholder section.
|
|
Reason: Honest documentation prevents broken deployments.
|
|
|
|
**Decision 3: Operations and security as separate files**
|
|
Chosen: `security.md` and `operations.md` are separate.
|
|
Reason: DevOps engineers frequently consult these independently — security during setup, operations during incidents.
|
|
|
|
## Migration Plan
|
|
|
|
Documentation only. No code changes. No rollback needed.
|
|
|
|
## Open Questions
|
|
|
|
*(none — scope fully defined)*
|