docs: DevOps documentation — complete docs/devops/ set

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>
This commit is contained in:
SentryAgent.ai Developer
2026-03-28 14:28:55 +00:00
parent 61ea975c79
commit d94a8cedc0
15 changed files with 1353 additions and 0 deletions

47
docs/devops/README.md Normal file
View File

@@ -0,0 +1,47 @@
# SentryAgent.ai AgentIdP — DevOps Documentation
Operational reference for engineers who deploy, configure, and maintain the AgentIdP infrastructure.
## System Overview
SentryAgent.ai AgentIdP is a Node.js REST API backed by PostgreSQL and Redis. It runs as a single stateless application process. All state lives in PostgreSQL (durable) and Redis (ephemeral cache and rate limiting).
**Stack:**
- **Runtime**: Node.js 18+ (TypeScript, compiled to JS)
- **Application**: Express 4.18 on port 3000
- **Database**: PostgreSQL 14+ (primary data store)
- **Cache**: Redis 7+ (token revocation, rate limiting, monthly token counters)
## Documentation
| Document | What it covers |
|----------|----------------|
| [Architecture](architecture.md) | Components, ports, data flow, Redis key patterns |
| [Environment Variables](environment-variables.md) | Every env var — required, optional, format, examples |
| [Database](database.md) | Schema (4 tables), migrations, how to apply and verify |
| [Local Development](local-development.md) | docker-compose setup, startup, health checks |
| [Security](security.md) | JWT key generation and rotation, CORS, secret storage |
| [Operations](operations.md) | Startup order, graceful shutdown, log interpretation, troubleshooting |
## Quick Reference — Ports
| Service | Port |
|---------|------|
| AgentIdP app | 3000 |
| PostgreSQL | 5432 |
| Redis | 6379 |
## Quick Reference — npm Scripts
| Script | Purpose |
|--------|---------|
| `npm run dev` | Run from TypeScript source (development) |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm start` | Run compiled output from `dist/` (production) |
| `npm run db:migrate` | Apply pending database migrations |
| `npm test` | Run all tests |
| `npm run test:unit` | Unit tests only |
## Developer Documentation
For API usage (registering agents, getting tokens, calling endpoints) — see [`docs/developers/`](../developers/README.md).