Deployment

Check Node.js Version

Pin your runtime to a supported Node.js version: ^20.19.0, ^22.12.0, or >=24.0.0. Check the exact version with node --version before the first deploy. Older versions like Node 18 will fail with modern Next.js and runtime API expectations.

Provision PostgreSQL

Create a hosted PostgreSQL database (e.g., Neon, Supabase, Railway) and update your DATABASE_URL environment variable.

Configure Environment Variables

Set all production env vars for your chosen auth provider, payment provider, email delivery, and server-side secrets.

Verify the production connection string

From the same environment that will run Prisma, confirm DATABASE_URL points at the intended PostgreSQL instance and that the credentials are valid. Do this before migrations so a bad connection string does not look like a Prisma or deployment failure.

Run Production Migrations

Apply your database schema to the new production database after DATABASE_URL is confirmed.

npm run prisma:deploy

Seed only if this is a brand-new database

Run the seed script one time if you want the starter admin, seeded plans, default settings, and editable site pages. Skip this on normal repeat deploys so you do not confuse setup with everyday releases.

npx prisma db seed

Configure Webhooks

Point your auth and payment provider webhooks to your new production domain and verify signatures are working.

Rotate Local Secrets

Generate new, secure random strings for ENCRYPTION_SECRET and other tokens. Never use your local development keys in production.

Use .env.local for development

Keep a local .env.local file on your laptop for rapid development and testing.

Set platform secrets

Set the real secrets in your platform env settings (Vercel, Coolify, etc.) first.

Optional: Centralize with a provider

If you want centralized secret management across platforms, opt into SECRETS_PROVIDER=infisical or SECRETS_PROVIDER=doppler. Install and authenticate the provider CLI in the real build/runtime environment first, then follow the dedicated Secrets & Providers guide for the provider-specific setup steps.

Verify environment

Run the smoke test to verify all required variables are present before your first deploy.

npm run secrets:smoke

Deploy

Deploy normally using your platform's standard migration, build, and start commands.

npm run prisma:deploy
npm run build
npm run start

Import project to Vercel

Import your repository into Vercel. Vercel will automatically detect that it is a Next.js project.

Set environment variables

Add all your production environment variables in the Vercel project settings.

Deploy database schema

Run the Prisma deploy command against your production PostgreSQL database before the first live release.

npm run prisma:deploy

Seed once if the database is empty

Run the seed script one time against the same production database only if you want the starter records. This is not part of every Vercel deploy.

npx prisma db seed

Configure durable uploads when needed

If users or admins will upload files, configure S3-compatible storage by setting FILE_STORAGE="s3" and the related credentials. On Vercel, persistent app-managed uploads should be treated as required S3 storage because the local filesystem is not a durable production store.

Enable background jobs

Set CRON_SECRET to a secure random string. The cron endpoint also accepts CRON_PROCESS_EXPIRY_TOKEN or CRON_TOKEN, but CRON_SECRET is the simplest default for the bundled Vercel scheduler.

Connect repository

Connect your repository to Coolify as a standard Node or Nixpacks-style application.

Set environment variables and runtime

Add your production env vars in the Coolify application settings and pin the runtime to a supported Node.js version before the first deploy. At minimum, configure DATABASE_URL, NEXT_PUBLIC_APP_URL, NEXT_PUBLIC_APP_DOMAIN, NEXT_PUBLIC_SITE_NAME, AUTH_PROVIDER, PAYMENT_PROVIDER, ENCRYPTION_SECRET, INTERNAL_API_TOKEN, HEALTHCHECK_TOKEN, CRON_PROCESS_EXPIRY_TOKEN, and your email/provider secrets.

Use a build-safe PostgreSQL URL

If your DATABASE_URL includes a file-based CA path like sslrootcert=/etc/ssl/certs/coolify-ca.crt, the build container may fail if that file is not present there. Prefer a URL that also works in the build container unless you are deliberately shipping that certificate into both build and runtime images.

Configure a pre-deploy migration step

Use Coolify's deployment hooks or pre-deploy command field so every release applies migrations automatically before the app is started. A one-time manual run is fine for rescue work, but it is not enough for an ongoing production workflow.

npm run prisma:deploy

Seed once if this is the first launch of a new database

Run the seed script a single time if you want the starter admin, plans, settings, and site pages. Do not wire seeding into every deployment hook.

npx prisma db seed

Set build and start commands

Configure the exact commands Coolify should use after migrations succeed.

Build: npm run deploy:build
Start: npm run start

Configure production storage if uploads must persist

If the app will store user-managed uploads, use S3-compatible storage instead of the container filesystem so assets survive container rebuilds, restarts, and reschedules.

Configure background jobs

Create a scheduled HTTP job in Coolify to hit the expiry cron endpoint hourly or daily. The route accepts CRON_PROCESS_EXPIRY_TOKEN, CRON_SECRET, or CRON_TOKEN; pick one name and use it consistently.

curl -i -m 60 \
+  -H "Authorization: Bearer $CRON_PROCESS_EXPIRY_TOKEN" \
+  "https://yourdomain.com/api/cron/process-expiry"

Validate the deployed service before cutover

After deploy, call the authorized health endpoint and verify the app is running with the expected database, auth, payment, and env configuration before sending traffic to it.