Releases

A release is a tagged build of Next.js, the API, the worker, and, when docs change, the documentation site. Database migrations run before the new API process starts taking traffic.

Pipeline

1. Install dependencies from the lockfile.
2. Typecheck and lint the API, worker, and Next.js app.
3. Build the documentation site when kstudeo-doc changed.
4. Run unit tests.
5. Run integration tests against an ephemeral PostgreSQL, including ledger immutability and webhook deduplication.
6. Run the gallery and booking end-to-end tests.
7. Publish images or build artifacts.
8. Apply Prisma migrations, then the SQL constraint migration if that release includes one.
9. Start the worker, then the API, then Next.js.
10. Send a provider test webhook in sandbox, or a signed fixture against staging, before pointing production webhooks at a new host.

The documentation site can deploy on its own. It has no migration.

Migration safety

• Expanding changes ship first: add a nullable column, deploy code that writes it, then enforce a constraint.
• The unique webhook key and the ledger trigger are already required in the first migration. Later releases do not drop them.
• A release that changes reward rounding needs a new policy row. It does not rewrite referral_rewards or reward_ledger.

Rollback

Application rollback is the previous build. Rolling back a migration that already dropped or rewrote data is a restore, not a down migration. Prefer migrations that only add objects until the release is known to be healthy.

If the new API fails after a compatible migration, start the previous API again. The worker should match the API version when job payloads change. Drain or finish old job types before removing the code that handles them.

Configuration

Production secrets are injected by the host. A release artifact does not contain .env. Confirm the live Stripe secret only on the production host. Staging stays on Stripe test keys. DATABASE_URL on each host points at that host's PostgreSQL database.