d42c653eea
- engineering-docs → archive/2026-03-29-engineering-docs (63/63 tasks complete) - phase-2-production-ready → archive/2026-03-29-phase-2-production-ready (89/89 tasks complete) - openspec/specs/ synced with all Phase 1 + Phase 2 + engineering-docs capabilities (22 specs total) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
29 lines
2.2 KiB
Markdown
29 lines
2.2 KiB
Markdown
## ADDED Requirements
|
|
|
|
### Requirement: Deployment and operations guide
|
|
The system SHALL include a document (`docs/engineering/10-deployment.md`) that explains how the application is built, deployed, and operated — covering Docker, Terraform, environment configuration, and monitoring.
|
|
|
|
#### Scenario: Docker build and run documented
|
|
- **WHEN** a new engineer reads 10-deployment.md
|
|
- **THEN** they SHALL understand the multi-stage Dockerfile (builder stage compiles TypeScript, production stage runs compiled JS with node:18-alpine and non-root USER node), how to build the image, and how to run it with the required environment variables
|
|
|
|
#### Scenario: Environment variables fully documented
|
|
- **WHEN** a new engineer needs to configure the application
|
|
- **THEN** the guide SHALL provide a complete table of all environment variables: name, purpose, required/optional, example value — covering database, Redis, JWT signing key, Vault, OPA, and rate limiting config
|
|
|
|
#### Scenario: Database migrations documented
|
|
- **WHEN** a new engineer needs to run or write migrations
|
|
- **THEN** the guide SHALL explain: where migration files live (`migrations/`), the naming convention, how to run them (`npm run migrate`), and how to write a new migration following the existing pattern
|
|
|
|
#### Scenario: Terraform multi-region deployment explained
|
|
- **WHEN** a new engineer reads 10-deployment.md
|
|
- **THEN** they SHALL understand the Terraform structure: what modules exist, what the three regions (US, EU, APAC) deploy, how to run `terraform plan` and `terraform apply`, and what AWS/GCP resources are provisioned
|
|
|
|
#### Scenario: Prometheus metrics and Grafana explained
|
|
- **WHEN** a new engineer reads 10-deployment.md
|
|
- **THEN** they SHALL find: which endpoint exposes metrics (`/metrics`), the key metrics tracked, how to access the Grafana dashboard locally (port, login), and how to add a new metric counter or histogram to the API server
|
|
|
|
#### Scenario: Operational runbook for common tasks
|
|
- **WHEN** a new engineer is on-call or supporting operations
|
|
- **THEN** the guide SHALL include a runbook covering: how to check application health, how to rotate the JWT signing key, how to revoke all tokens for a compromised agent, and how to read audit logs for an incident
|