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>
72 lines
4.3 KiB
Markdown
72 lines
4.3 KiB
Markdown
## 1. Folder Structure & Index
|
|
|
|
- [x] 1.1 Create `docs/devops/` directory
|
|
- [x] 1.2 Create `docs/devops/README.md` — index + system overview (what AgentIdP is, what this folder covers, links to all docs)
|
|
|
|
## 2. Architecture
|
|
|
|
- [x] 2.1 Create `docs/devops/architecture.md` — component diagram (Express, PostgreSQL, Redis) with roles and responsibilities
|
|
- [x] 2.2 Document all service ports (app: 3000, PostgreSQL: 5432, Redis: 6379)
|
|
- [x] 2.3 Document data flow: request → auth middleware → rate limit → controller → service → repository → PostgreSQL/Redis
|
|
- [x] 2.4 Document Redis usage: token revocation keys, rate limit counters, monthly token counts
|
|
- [x] 2.5 Document graceful shutdown: SIGTERM/SIGINT handling, server.close(), process.exit(0)
|
|
|
|
## 3. Environment Variables
|
|
|
|
- [x] 3.1 Create `docs/devops/environment-variables.md` — complete reference table
|
|
- [x] 3.2 Document required vars: DATABASE_URL, REDIS_URL, JWT_PRIVATE_KEY, JWT_PUBLIC_KEY
|
|
- [x] 3.3 Document optional vars: PORT (default 3000), NODE_ENV, CORS_ORIGIN (default *)
|
|
- [x] 3.4 Add format notes: DATABASE_URL connection string format, REDIS_URL format, PEM key format
|
|
- [x] 3.5 Add `.env` file example with all vars populated
|
|
|
|
## 4. Database
|
|
|
|
- [x] 4.1 Create `docs/devops/database.md` — schema overview section
|
|
- [x] 4.2 Document `agents` table: all columns, types, constraints, indexes
|
|
- [x] 4.3 Document `credentials` table: all columns, types, constraints, indexes, FK to agents
|
|
- [x] 4.4 Document `audit_events` table: all columns, types, constraints, indexes, append-only design
|
|
- [x] 4.5 Document `token_revocations` table: all columns, types, indexes, dual-store design (Redis + PG)
|
|
- [x] 4.6 Document migration runner: how it works, commands to run, how to verify applied migrations
|
|
- [x] 4.7 Document `schema_migrations` tracking table
|
|
|
|
## 5. Local Development
|
|
|
|
- [x] 5.1 Create `docs/devops/local-development.md` — prerequisites (Docker, Node.js 18+)
|
|
- [x] 5.2 Document infrastructure-only docker-compose startup (postgres + redis only, not app service)
|
|
- [x] 5.3 Document service ports and health check verification commands
|
|
- [x] 5.4 Document migration step: exact `npm run db:migrate` command and expected output
|
|
- [x] 5.5 Document application startup: `npm run dev` vs `npm start` (compiled), expected log output
|
|
- [x] 5.6 Note Dockerfile gap: app service in docker-compose.yml requires Dockerfile (Phase 1 P1 pending)
|
|
- [x] 5.7 Document full docker-compose stack startup (for when Dockerfile is available)
|
|
- [x] 5.8 Document stopping and cleaning up: `docker-compose down` and volume removal
|
|
|
|
## 6. Security
|
|
|
|
- [x] 6.1 Create `docs/devops/security.md` — JWT key management section
|
|
- [x] 6.2 Document RSA-2048 keypair generation using openssl (exact commands)
|
|
- [x] 6.3 Document PEM format for env vars (newlines as \n in single-line env, or file path approach)
|
|
- [x] 6.4 Document key rotation procedure: generate new pair, update env, restart server, old tokens expire naturally
|
|
- [x] 6.5 Document CORS configuration: CORS_ORIGIN env var, wildcard vs specific origin
|
|
- [x] 6.6 Document secret storage guidance: never commit .env, use secrets manager in production
|
|
- [x] 6.7 Document bcrypt: credentials are stored as bcrypt hashes, plaintext never persisted
|
|
|
|
## 7. Operations
|
|
|
|
- [x] 7.1 Create `docs/devops/operations.md` — startup checklist
|
|
- [x] 7.2 Document startup order: PostgreSQL → Redis → run migrations → start app
|
|
- [x] 7.3 Document graceful shutdown: send SIGTERM, server drains in-flight requests, exits 0
|
|
- [x] 7.4 Document log output format: what each startup log line means
|
|
- [x] 7.5 Document troubleshooting: DATABASE_URL not set, REDIS_URL not set, JWT keys not set
|
|
- [x] 7.6 Document troubleshooting: PostgreSQL connection refused (service not ready)
|
|
- [x] 7.7 Document troubleshooting: Redis connection error (service not ready)
|
|
- [x] 7.8 Document troubleshooting: migration fails (connection issue vs SQL error)
|
|
- [x] 7.9 Document Redis key patterns used by the application (rate:, revoked:, monthly:)
|
|
|
|
## 8. QA & Review
|
|
|
|
- [x] 8.1 Verify all commands are exact and runnable (no placeholders in shell commands)
|
|
- [x] 8.2 Verify all env var names match source code exactly
|
|
- [x] 8.3 Verify all table/column names match migration SQL exactly
|
|
- [x] 8.4 Verify all port numbers match docker-compose.yml
|
|
- [x] 8.5 Verify all internal links resolve
|