# 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