Deploy Payload CMS on a VPS: complete guide

Payload CMS takes a radically code-first approach: your content schema is defined in TypeScript configuration files, versioned with Git, and since version 3 Payload installs directly inside a Next.js application via the App Router. This means a VPS lets you host both the CMS and the front-end in a single Node process, sharing the same build and runtime. You get end-to-end typing, schema migrations managed in code, and no dependency on a GUI to model your content. Self-hosting is the natural choice here: Payload is designed to be deployed like any Next.js app, and a VPS gives you full control over the database (MongoDB or PostgreSQL), uploads, and environment variables, without any intermediary platform.

Since Payload runs on Next.js, the build is demanding: plan for a VPS with 2 vCPU and 4 GB RAM to build and run the application comfortably, especially if the Next.js front is large. Install Node.js 20 LTS, Docker and Docker Compose. On the database side, provision MongoDB 7 or PostgreSQL 16 depending on your chosen adapter (@payloadcms/db-mongodb or @payloadcms/db-postgres). Point your domain to the VPS IP. Budget 15 GB of disk space for node_modules, the .next build, uploads and database backups.

Payload 3 manages users through the users collection defined in payload.config.ts. Enable authentication on the collection with auth: true — this automatically adds the /api/users/login, /api/users/logout, /api/users/me and /api/users/refresh-token endpoints.

For roles, Payload does not impose a model: define a role field (type select) on the users collection, then drive access via access functions at the collection and operation level:

access: {
  read: ({ req: { user } }) => user?.role === 'admin',
  create: isAdmin,
  update: isAdminOrSelf,
  delete: isAdmin,
}

For programmatic access (CI, third-party integrations), use API keys: enable useAPIKey: true in the collection's auth config. Each user can then generate a key from the admin panel. Pass it in the Authorization: users API-Key your-key header. API keys are hashed in the database — a lost key cannot be recovered, it must be regenerated.

Payload 3's collection hooks let you run code before or after each CRUD operation. They replace webhooks cleanly when logic lives in the same runtime:

hooks: {
  afterChange: [
    async ({ doc, operation }) => {
      if (operation === 'create') {
        await notifySubscribers(doc)
      }
    },
  ],
  beforeDelete: [
    async ({ id }) => {
      await cleanupMedia(id)
    },
  ],
}

Available hooks are beforeOperation, beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete and afterDelete. An afterChange hook is ideal for invalidating a CDN cache, sending a notification, or syncing with an external service after publication.

For outbound HTTP webhooks (notifying a static site, Slack, or a build pipeline), Payload has no dedicated module but afterChange hooks suffice: a simple fetch to your target endpoint inside the hook covers the use case. Avoid blocking the response on an external request — wrap the call in setImmediate or a background process if latency matters.

Payload 3 follows semantic versioning. Patch updates (3.x.y → 3.x.z) are safe to apply without migrations. Minor updates (3.x → 3.y) may add columns or indexes and require running payload migrate.

Recommended workflow for each update:

# 1. Bump the version in package.json
npm install [email protected] @payloadcms/[email protected]

# 2. Generate a migration file if the schema changed
npx payload migrate:create

# 3. Test locally on a database copy
npx payload migrate

# 4. Commit the migration file with the version bump
git add src/migrations/ package.json package-lock.json
git commit -m "chore: payload 3.88.0"

# 5. In production: stop app, apply migrations, restart
docker compose run --rm app npx payload migrate
docker compose up -d app

Never manually edit generated files in src/migrations/: Payload verifies them by hash. A modified file causes migrate to fail with Error: Migration file has been modified since it was created. To roll back a migration: npx payload migrate:down.

This is the most common deployment obstacle on a VPS, and it takes three distinct forms. The most confusing is Unsupported CPU: prebuilt binaries for linux-x64 require v2 microarchitecture: it comes from the machine's processor, not your code or dependencies. Pre-compiled binaries target an instruction set that older CPUs do not expose — this is a VPS selection criterion, not a bug to fix. The second, Could not load the "sharp" module using the linux-x64 runtime, almost always indicates a node_modules built on a different platform, typically a macOS development machine copied to a Linux server: reinstall on the target machine rather than copying the folder. The third is specific to multi-stage Docker: sharp installed in the build stage only, absent from the runtime stage — the container starts then fails on the first image operation. Install it explicitly in the final stage. On ARM architecture, the same vigilance applies: the library must be resolved for that platform.

Build OOM — Killed or JavaScript heap out of memory.
Occurs during npm run build when available RAM is below 3 GB. Node.js is limited to ~1.8 GB by default. Set NODE_OPTIONS=--max-old-space-size=3072 in the environment before the build, or build the image on a more powerful machine and push to a registry.

PostgreSQL — Error: connect ECONNREFUSED 127.0.0.1:5432.
The app tries to connect before PostgreSQL is ready, or the connection URL points to localhost instead of the Docker service name (postgres). Verify that DATABASE_URI uses the service name (postgresql://payload:pass@postgres:5432/payload) and that the healthcheck is in place (see step 3).

Admin inaccessible in prod — /admin returns 404 or redirect loop.
Two main causes: serverURL not set or not matching the real URL (Payload generates its internal redirects from this value), or the X-Forwarded-Proto: https header missing from the Nginx reverse proxy. Add proxy_set_header X-Forwarded-Proto $scheme; to the vhost and verify serverURL matches the public origin exactly, without a trailing slash.

CORS — Access-Control-Allow-Origin missing on the API.
Payload reads cors from payload.config.ts. In production, list your allowed origins explicitly: cors: { origins: ['https://example.com'] }. Leaving cors: '*' accepts all origins, which may be appropriate for a public API but exposes the admin to cross-origin requests. cors: { origins: [serverURL] } is the minimal safe setting.

Error: Migration file has been modified since it was created.
A file in src/migrations/ was manually edited after generation. Payload verifies the integrity of each file. Restore the original from Git, generate a new migration file if the schema changed, and reapply in order.