Harden production deployment workflow

2026-04-28 01:09:17 +08:00
parent c8ccaa9925
commit 46a72f815e
23 changed files with 243 additions and 21 deletions
@@ -0,0 +1,61 @@
+# 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.