sentryagent-idp/openspec/changes/archive/2026-04-02-devops-documentation/tasks.md

1. Folder Structure & Index

• 1.1 Create docs/devops/ directory
• 1.2 Create docs/devops/README.md — index + system overview (what AgentIdP is, what this folder covers, links to all docs)

2. Architecture

• 2.1 Create docs/devops/architecture.md — component diagram (Express, PostgreSQL, Redis) with roles and responsibilities
• 2.2 Document all service ports (app: 3000, PostgreSQL: 5432, Redis: 6379)
• 2.3 Document data flow: request → auth middleware → rate limit → controller → service → repository → PostgreSQL/Redis
• 2.4 Document Redis usage: token revocation keys, rate limit counters, monthly token counts
• 2.5 Document graceful shutdown: SIGTERM/SIGINT handling, server.close(), process.exit(0)

3. Environment Variables

• 3.1 Create docs/devops/environment-variables.md — complete reference table
• 3.2 Document required vars: DATABASE_URL, REDIS_URL, JWT_PRIVATE_KEY, JWT_PUBLIC_KEY
• 3.3 Document optional vars: PORT (default 3000), NODE_ENV, CORS_ORIGIN (default *)
• 3.4 Add format notes: DATABASE_URL connection string format, REDIS_URL format, PEM key format
• 3.5 Add .env file example with all vars populated

4. Database

• 4.1 Create docs/devops/database.md — schema overview section
• 4.2 Document agents table: all columns, types, constraints, indexes
• 4.3 Document credentials table: all columns, types, constraints, indexes, FK to agents
• 4.4 Document audit_events table: all columns, types, constraints, indexes, append-only design
• 4.5 Document token_revocations table: all columns, types, indexes, dual-store design (Redis + PG)
• 4.6 Document migration runner: how it works, commands to run, how to verify applied migrations
• 4.7 Document schema_migrations tracking table

5. Local Development

• 5.1 Create docs/devops/local-development.md — prerequisites (Docker, Node.js 18+)
• 5.2 Document infrastructure-only docker-compose startup (postgres + redis only, not app service)
• 5.3 Document service ports and health check verification commands
• 5.4 Document migration step: exact npm run db:migrate command and expected output
• 5.5 Document application startup: npm run dev vs npm start (compiled), expected log output
• 5.6 Note Dockerfile gap: app service in docker-compose.yml requires Dockerfile (Phase 1 P1 pending)
• 5.7 Document full docker-compose stack startup (for when Dockerfile is available)
• 5.8 Document stopping and cleaning up: docker-compose down and volume removal

6. Security

• 6.1 Create docs/devops/security.md — JWT key management section
• 6.2 Document RSA-2048 keypair generation using openssl (exact commands)
• 6.3 Document PEM format for env vars (newlines as \n in single-line env, or file path approach)
• 6.4 Document key rotation procedure: generate new pair, update env, restart server, old tokens expire naturally
• 6.5 Document CORS configuration: CORS_ORIGIN env var, wildcard vs specific origin
• 6.6 Document secret storage guidance: never commit .env, use secrets manager in production
• 6.7 Document bcrypt: credentials are stored as bcrypt hashes, plaintext never persisted

7. Operations

• 7.1 Create docs/devops/operations.md — startup checklist
• 7.2 Document startup order: PostgreSQL → Redis → run migrations → start app
• 7.3 Document graceful shutdown: send SIGTERM, server drains in-flight requests, exits 0
• 7.4 Document log output format: what each startup log line means
• 7.5 Document troubleshooting: DATABASE_URL not set, REDIS_URL not set, JWT keys not set
• 7.6 Document troubleshooting: PostgreSQL connection refused (service not ready)
• 7.7 Document troubleshooting: Redis connection error (service not ready)
• 7.8 Document troubleshooting: migration fails (connection issue vs SQL error)
• 7.9 Document Redis key patterns used by the application (rate:, revoked:, monthly:)

8. QA & Review

• 8.1 Verify all commands are exact and runnable (no placeholders in shell commands)
• 8.2 Verify all env var names match source code exactly
• 8.3 Verify all table/column names match migration SQL exactly
• 8.4 Verify all port numbers match docker-compose.yml
• 8.5 Verify all internal links resolve