From 4d6e17a13b3ee4a00d93713a223871e96ee94550 Mon Sep 17 00:00:00 2001
From: Citali <git@fellies.email>
Date: Wed, 11 Feb 2026 12:11:08 +0100
Subject: [PATCH] docs(ops): add environment and deployment runbook

---
 TODO.md                                       |   2 +-
 docs/.vitepress/config.mts                    |   1 +
 .../environment-runbook.md                    | 103 ++++++++++++++++++
 docs/product-engineering/index.md             |   1 +
 4 files changed, 106 insertions(+), 1 deletion(-)
 create mode 100644 docs/product-engineering/environment-runbook.md

diff --git a/TODO.md b/TODO.md
index 4aac56f..12fa854 100644
--- a/TODO.md
+++ b/TODO.md
@@ -75,7 +75,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P1] RBAC and permission model documentation in docs site
 - [x] [P2] i18n conventions docs (keys, namespaces, fallback, translation workflow)
 - [x] [P1] CRUD base patterns documentation and examples
-- [ ] [P1] Environment and deployment runbook docs (dev/staging/production)
+- [x] [P1] Environment and deployment runbook docs (dev/staging/production)
 - [ ] [P2] API and domain glossary pages
 - [ ] [P2] Architecture Decision Records (ADR) structure and first ADRs
 
diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
index b9bf739..7ee899f 100644
--- a/docs/.vitepress/config.mts
+++ b/docs/.vitepress/config.mts
@@ -25,6 +25,7 @@ export default defineConfig({
           { text: "i18n Baseline", link: "/product-engineering/i18n-baseline" },
           { text: "i18n Conventions", link: "/product-engineering/i18n-conventions" },
           { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" },
+          { text: "Environment Runbook", link: "/product-engineering/environment-runbook" },
           { text: "Testing Strategy", link: "/product-engineering/testing-strategy" },
           { text: "Workflow", link: "/workflow" },
         ],
diff --git a/docs/product-engineering/environment-runbook.md b/docs/product-engineering/environment-runbook.md
new file mode 100644
index 0000000..c5a557b
--- /dev/null
+++ b/docs/product-engineering/environment-runbook.md
@@ -0,0 +1,103 @@
+# Environment and Deployment Runbook
+
+## Scope
+
+Operational baseline for `dev`, `staging`, and `production`.
+
+## Environments
+
+### Dev (local)
+
+- Runtime: Bun + local Next dev servers
+- Entry point: `bun run dev`
+- Database: local/remote dev Postgres from `.env`
+- Characteristics:
+  - fastest feedback
+  - non-production data acceptable
+  - migrations created here first
+
+### Staging
+
+- Runtime: Docker Compose (`docker-compose.staging.yml`)
+- Purpose: integration validation and release candidate checks
+- Characteristics:
+  - production-like environment
+  - controlled test data
+  - candidate for production promotion
+
+### Production
+
+- Runtime: Docker Compose (`docker-compose.production.yml`)
+- Purpose: end-user traffic
+- Characteristics:
+  - protected secrets and stricter access controls
+  - immutable release artifacts
+  - rollback procedures required
+
+## Core Commands
+
+### Local development
+
+```bash
+bun install
+bun run db:generate
+bun run db:migrate
+bun run db:seed
+bun run dev
+```
+
+### Staging compose
+
+```bash
+bun run docker:staging:up
+bun run docker:staging:down
+```
+
+### Production compose
+
+```bash
+bun run docker:production:up
+bun run docker:production:down
+```
+
+## Release Flow
+
+1. Complete work on task branch.
+2. Merge into `dev` and pass quality gates.
+3. Promote `dev` -> `staging`.
+4. Validate staging smoke/e2e + manual checks.
+5. Promote `staging` -> `main` and tag release.
+
+## Migration Policy
+
+- Create migrations in development only.
+- Apply migrations in deployment using `prisma migrate deploy`.
+- Never hand-edit applied migration history.
+
+## Rollback Baseline
+
+Current baseline strategy:
+
+- rollback app image/tag to previous known-good release
+- restore database from backup when schema/data changes require recovery
+
+## Secrets and Config
+
+- Dev: `.env`
+- Staging: `.env.staging` (from `.env.staging.example`)
+- Production: `.env.production` (from `.env.production.example`)
+
+Minimum sensitive values:
+
+- `DATABASE_URL`
+- `BETTER_AUTH_SECRET`
+- `CMS_SUPPORT_*` credentials/keys
+
+## Verification Checklist
+
+- `bun run check`
+- `bun run typecheck`
+- `bun run test`
+- `bun run test:e2e`
+- app startup health for web/admin
+- login flow and permissions smoke
diff --git a/docs/product-engineering/index.md b/docs/product-engineering/index.md
index 9251b54..7da1df0 100644
--- a/docs/product-engineering/index.md
+++ b/docs/product-engineering/index.md
@@ -10,6 +10,7 @@ This section covers platform and implementation documentation for engineers and
 - [RBAC And Permissions](/product-engineering/rbac-permission-model)
 - [i18n Conventions](/product-engineering/i18n-conventions)
 - [CRUD Examples](/product-engineering/crud-examples)
+- [Environment Runbook](/product-engineering/environment-runbook)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
 - [Workflow](/workflow)