# Deployment Runbook

This runbook is the source of truth for taking the Eversolo Payload/Next.js site from a local database and media folder to a production deployment.

## Release Inputs

- Git commit to deploy.
- PostgreSQL database dump exported from the approved local database.
- `media/` and `files/` directories exported from the same local workspace as the database dump.
- Production environment variables from `.env.example`, filled with production values.

## Required Environment

Use Node.js 22 LTS or newer. The project declares `>=20.9.0`, but production should use one pinned LTS line.

Required variables:

- `NEXT_PUBLIC_SITE_URL`: public canonical origin, for example `https://www.eversolo.com`.
- `PAYLOAD_SECRET`: long random secret, never use the example value.
- `DATABASE_URI`: PostgreSQL connection string.
- `PAYLOAD_DB_PUSH=false`: production must use migrations, not schema push.
- `PAYLOAD_RUN_MIGRATIONS_ON_START=false`: production startup should not run migrations interactively.

Optional variables:

- `PORT`: runtime port for `next start`.
- `SMOKE_BASE_URL`: base URL used by `npm run smoke`.

## Deployment Steps

1. Restore the approved PostgreSQL dump into the production database.
2. Copy `media/` and `files/` to the production persistent upload volume.
3. Install dependencies with `npm ci`.
4. Run `npm run generate:types` only during build validation, not as a production data mutation step.
5. Run `npm run typecheck`.
6. Run `npm run build`.
7. Run `npm run payload:migrate`.
8. Run `npm run payload:migrate:status` and confirm every migration is `Yes`.
9. Start the app with `npm run start`.
10. Run `npm run smoke -- "$NEXT_PUBLIC_SITE_URL"`.

## Data Rules

- Do not run `PAYLOAD_DB_PUSH=true` against production.
- Do not rely on application startup to run migrations. Use the explicit migration step.
- Before exporting a local database for production, confirm `payload_migrations` has no `batch = -1` dev marker. That marker means schema push history is still recorded and production migration commands can prompt interactively.
- Do not edit migrations after they have shipped to production. Add a new forward migration instead.
- Keep schema migrations and data backfills separate. Backfill scripts in `src/scripts/` are manual operational tools, not automatic boot steps.
- The deployed database and upload directories must come from the same local export, otherwise media relationships can point at missing files.

## Rollback

Rollback means switching code and data together:

1. Stop traffic or move traffic back to the previous deployment.
2. Restore the previous database dump.
3. Restore the matching previous `media/` and `files/` directories.
4. Deploy the previous Git commit.
5. Re-run smoke checks before reopening traffic.

Do not run migration down scripts on production as the default rollback path.