Skip to content
PayloadCMS Boilerplate

Environment Variables

This page covers every environment variable the boilerplate reads, when each is required, and how to add your own with runtime validation.

Required Variables

Section titled “Required Variables”

PAYLOAD_SECRET

Section titled “PAYLOAD_SECRET”

Secret key for PayloadCMS authentication. Generate one at payloadsecret.io.

Terminal window
PAYLOAD_SECRET=your-secure-secret

DATABASE_URI

Section titled “DATABASE_URI”

PostgreSQL connection string.

Terminal window
# Local (DDEV)
DATABASE_URI=postgres://db:db@db:5432/db


# Production
DATABASE_URI=postgres://user:pass@host:5432/dbname

NEXT_PUBLIC_SERVER_URL

Section titled “NEXT_PUBLIC_SERVER_URL”

Your site’s public URL.

Terminal window
# Local
NEXT_PUBLIC_SERVER_URL=https://yourproject.ddev.site


# Production
NEXT_PUBLIC_SERVER_URL=https://yourdomain.com

Optional Variables

Section titled “Optional Variables”

APP_ENV

Section titled “APP_ENV”
Terminal window
APP_ENV=development  # development | staging | production

PAYLOAD_ADMIN_RECOVERY_SECRET

Section titled “PAYLOAD_ADMIN_RECOVERY_SECRET”

Secret for admin account recovery when locked out.

Terminal window
PAYLOAD_ADMIN_RECOVERY_SECRET=your-secure-secret-here

Recovery steps:

  1. Set this in .env
  2. Call the recovery endpoint:
Terminal window
curl -X POST http://localhost:3000/admin-recovery \
  -H "Content-Type: application/json" \
  -d '{"secret": "your-secure-secret-here", "email": "your@email.com", "password": "newpassword"}'
  1. If the email exists, their role will be updated to admin
  2. If the email doesn’t exist, a new admin user will be created (password required)

Note: If not set, recovery is disabled.

PAYLOAD_MAX_VERSIONS_TO_KEEP

Section titled “PAYLOAD_MAX_VERSIONS_TO_KEEP”

How many document versions to retain.

Terminal window
PAYLOAD_MAX_VERSIONS_TO_KEEP=10  # Default: 3

NEXT_PUBLIC_SITE_NAME

Section titled “NEXT_PUBLIC_SITE_NAME”

Display name for SEO and OpenGraph.

Terminal window
NEXT_PUBLIC_SITE_NAME="My Project"

Production Deployment (Coolify)

Section titled “Production Deployment (Coolify)”
VariableValue
DATABASE_URICoolify Postgres connection string
NEXT_PUBLIC_SERVER_URL$COOLIFY_URL

Adding New Variables

Section titled “Adding New Variables”

New variables must be registered in three places to be validated at runtime.

  1. Add to .env.example

    .env.example
    NEXT_PUBLIC_FEATURE_FLAG=false

  2. Add validation in src/env.ts

    src/env.ts
    client: {
        NEXT_PUBLIC_FEATURE_FLAG: z.boolean().default(false),
    },
    experimental__runtimeEnv: {
        NEXT_PUBLIC_FEATURE_FLAG: process.env.NEXT_PUBLIC_FEATURE_FLAG,
    },

  3. Set the local value in .env

    .env
    NEXT_PUBLIC_FEATURE_FLAG=true

Naming Convention

Section titled “Naming Convention”
  • NEXT_PUBLIC_* — Exposed to browser
  • PAYLOAD_* — PayloadCMS server-only
  • APP_* — Application settings

Troubleshooting

Section titled “Troubleshooting”
ErrorSolution
”Missing required variable”Check .env file exists and contains the variable
”Invalid DATABASE_URI”Verify PostgreSQL connection string format
Changes not workingRestart: ddev pnpm dev