website/docs/deployment-runbook.md

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.