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.

For the command-level Chinese handoff guide, see docs/local-db-to-production-deployment.md.

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. Run local release checks: npm run lint, npm run typecheck, npm run build, and npm run payload:migrate:status.
2. Load the local release environment with set -a; source .env; set +a, then confirm the local release database has no dev marker: psql "$DATABASE_URI" -Atc "select count(*) from payload_migrations where batch = -1;".
3. Export the approved PostgreSQL database: pg_dump --format=custom --no-owner --no-acl --file=eversolo.payload.dump "$DATABASE_URI".
4. Export matching uploads: tar -czf eversolo.uploads.tgz media files.
5. Restore the approved PostgreSQL dump into the production database with pg_restore --no-owner --no-acl.
6. Copy media/ and files/ to the production persistent upload volume.
7. Install dependencies with npm ci.
8. Run npm run generate:types only during build validation, not as a production data mutation step.
9. Run npm run typecheck.
10. Run npm run build.
11. Run npm run payload:migrate.
12. Run npm run payload:migrate:status and confirm every migration is Yes.
13. Start the app with npm run start.
14. Run npm run smoke -- "$NEXT_PUBLIC_SITE_URL".
15. Log out of the admin, open /admin/login, and confirm the verification code is required before password validation.

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.
• Admin login captcha is stateless and signed with PAYLOAD_SECRET; changing that secret invalidates existing login sessions and outstanding captcha tokens.

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.