All deployment configuration lives in environment variables - database, secrets, object storage, email, and your license key. This page is the reference for what each variable does and how the license check behaves at runtime.

The scaffolder writes a working .env for local development. In production, set these in your hosting platform's environment settings - a local .env file is not read on most platforms.

Core

# Database connection - Postgres or libSQL/Turso URL
DATABASE_URL=postgresql://user:password@host:5432/dbname

# Secret used by Payload to sign auth tokens. Long random string; never reuse across apps.
PAYLOAD_SECRET=your-long-random-secret

# Site identifier - which site (row in the apps table) this deployment serves.
# One database can host unlimited sites; this pins a single-site deployment to its site.
CHAIBUILDER_APP_KEY=my-app

# Canonical site URL, used for licensing and absolute URL generation.
SITE_URL=https://www.example.com

Notes:

• PAYLOAD_SECRET - changing it invalidates all existing sessions. Generate with openssl rand -hex 32.
• SITE_URL - on Vercel you can omit it; the platform-provided VERCEL_PROJECT_PRODUCTION_URL is used to build the base URL when set.
• NEXT_PUBLIC_SERVER_URL - optional fallback origin for scripts and tests when no request host is available; not needed on most deployments.

License

# ChaiBuilder license key - optional during the 30-day trial, required after it
CHAIBUILDER_LICENSE_KEY=your_license_key_here

The license key is read only from this environment variable - it cannot be set in code or config. An empty value means trial mode, which starts the moment you deploy. The app validates the license automatically in the background; allow outbound HTTPS from your deployment. An expired trial or license shows a renew/downgrade notice in the builder - published pages keep serving. See Trial & Licensing for how the trial and license periods work.

Object storage (media)

BUCKET_NAME=your-bucket
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
S3_REGION=auto
S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com

Required for media uploads to persist in production. The first three switch storage on; S3_REGION defaults to auto and S3_ENDPOINT is optional (omit it on AWS S3). Full setup and per-provider values: Storage Configuration.

Email (optional)

EMAIL_FROM_ADDRESS=noreply@example.com
EMAIL_FROM_NAME=My Site
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=smtp-user
SMTP_PASS=smtp-password

Used for password resets and transactional email. When SMTP_HOST is unset in development, a disposable test inbox is used automatically so email flows still work locally.

Admin panel URL (optional)

# Custom admin path, no leading slash. Server-side value wins.
PAYLOAD_ADMIN_ROUTE=cms-a8f3k2m9

By default the CMS admin panel and the visual builder live under /admin. Setting this moves both, along with the revalidation route, password reset links, and the robots.txt disallow entry. The value must be at least 4 characters and is validated at build time, so a bad value fails the deploy. NEXT_PUBLIC_PAYLOAD_ADMIN_ROUTE is derived automatically - you do not set it yourself.

The change takes effect on the next build, not on restart alone. Requests to /admin then redirect to the custom path, which makes this hardening against scanners rather than access control. Full rules, wiring, and helpers for building admin URLs in your own code: Admin Route.

Revalidation token (optional)

# Bearer token for the manual revalidation route. Unset = route disabled.
REVALIDATE_TOKEN=your-random-token

Required only if an external system needs to purge page caches via POST /admin/api/revalidate - see Caching & Revalidation.

Postgres schema (optional)

# Create all tables in a named schema instead of "public"
CHAIBUILDER_POSTGRES_SCHEMA=chaibuilder

See Database Setup.

Per-environment checklist

Variable	Local dev	Production
DATABASE_URL	scaffolder-written	required
PAYLOAD_SECRET	scaffolder-written	required, unique
CHAIBUILDER_APP_KEY	scaffolder-written	required
SITE_URL	optional	recommended (omit on Vercel)
CHAIBUILDER_LICENSE_KEY	optional	required after trial
BUCKET_NAME + S3 vars	optional	required for media
SMTP_*	optional (test inbox)	required for email
PAYLOAD_ADMIN_ROUTE	optional	optional

Related

• Trial & Licensing - trial, plans, and the license period.
• Database Setup - DATABASE_URL details and pooling.
• Storage Configuration - the S3 variables in depth.