d94a8cedc0
Adds the full devops-documentation OpenSpec change implementation. Separate from docs/developers/ — serves a different audience (operators, not API consumers). docs/devops/: - README.md — index and system overview - architecture.md — components, ports, data flow, Redis key patterns - environment-variables.md — all 7 env vars (required + optional, formats, .env example) - database.md — 4-table schema, indexes, constraints, migration runner - local-development.md — docker-compose setup, health checks, startup, Dockerfile gap noted - security.md — RSA key generation/rotation, CORS, bcrypt, secret storage guidance - operations.md — startup order, graceful shutdown, log reference, troubleshooting QA gates: 48/48 tasks complete. All env vars verified against source. All table names verified against migrations. All ports verified against docker-compose.yml. All internal links resolve. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.2 KiB
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 fromdocs/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)