cms.fellies.org/docs/product-engineering/environment-runbook.md

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

bun install
bun run db:generate
bun run db:migrate
bun run db:seed
bun run dev

Staging compose

bun run docker:staging:up
bun run docker:staging:down

Production compose

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