Desplegar Payload CMS en un VPS: guía completa

Payload CMS adopta un enfoque radicalmente code-first: el esquema de contenido se define en TypeScript en archivos de configuración versionados con Git, y desde la versión 3 Payload se instala directamente en una aplicación Next.js mediante el App Router. Esto significa que un VPS permite alojar el CMS y el front en un único proceso Node, compartiendo el mismo build y runtime. Se obtiene tipado de extremo a extremo, migraciones de esquema gestionadas en el código y ninguna dependencia de una GUI para modelar los contenidos. El auto-alojamiento es la opción natural: Payload está diseñado para desplegarse como cualquier app Next.js, y un VPS da el control total sobre la base de datos (MongoDB o PostgreSQL), las subidas y las variables de entorno, sin plataforma intermediaria.

Como Payload funciona sobre Next.js, el build es exigente: planifica un VPS con 2 vCPU y 4 GB de RAM para construir y ejecutar la aplicación con comodidad. Instala Node.js 22 o 24 (Payload 3.93 exige ^22.23.4 || >=24.22.1; Node 20 ya no se admite), Docker y Docker Compose. Para la base de datos, aprovisiona MongoDB 7 o PostgreSQL 16 según el adaptador elegido (@payloadcms/db-mongodb o @payloadcms/db-postgres). Apunta tu dominio a la IP del VPS. Reserva 15 GB de disco para node_modules, el build .next, las subidas y las copias de seguridad de la base de datos.

Payload 3 gestiona los usuarios mediante la colección users definida en payload.config.ts. Activa la autenticación en la colección con auth: true — esto añade automáticamente los endpoints /api/users/login, /api/users/logout, /api/users/me y /api/users/refresh-token.

Para los roles, Payload no impone un modelo: define un campo role (tipo select) en la colección users, luego controla el acceso mediante funciones access a nivel de colección y operación:

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

Para el acceso programático (CI, integraciones de terceros), usa las API keys: activa useAPIKey: true en la configuración de autenticación de la colección. Los usuarios con acceso de admin pueden generar, regenerar o revocar una clave desde el panel de admin. Pásala en la cabecera Authorization: users API-Key tu-clave. La clave solo se muestra una vez: Payload la cifra en la base de datos con PAYLOAD_SECRET y no vuelve a mostrarla — una clave perdida se regenera, y cambiar PAYLOAD_SECRET invalida todas las claves existentes.

Los collection hooks de Payload 3 permiten ejecutar código antes o después de cada operación CRUD. Reemplazan elegantemente a los webhooks cuando la lógica vive en el mismo runtime:

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

Los hooks de colección son beforeOperation, beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete, afterDelete, afterOperation y afterError; las colecciones de autenticación añaden, entre otros, beforeLogin, afterLogin y afterLogout. Un hook afterChange es ideal para invalidar una caché CDN, enviar una notificación o sincronizar con un servicio externo tras la publicación.

Para webhooks HTTP salientes (notificar a un sitio estático, Slack o un pipeline de build), Payload no dispone de módulo dedicado pero los hooks afterChange bastan: un simple fetch al endpoint objetivo dentro del hook cubre el caso de uso.

Payload 3 sigue el versionado semántico. Las actualizaciones de patch (3.x.y → 3.x.z) son seguras sin migraciones. Las actualizaciones minor (3.x → 3.y) pueden añadir columnas o índices y requieren ejecutar payload migrate.

Flujo de trabajo recomendado para cada actualización:

# 1. Actualizar la versión en package.json
npm install [email protected] @payloadcms/[email protected]

# 2. Generar archivo de migración si el esquema cambió
npx payload migrate:create

# 3. Probar localmente sobre una copia de la base de datos
npx payload migrate

# 4. Confirmar el archivo de migración con el bump de versión
git add src/migrations/ package.json package-lock.json
git commit -m "chore: payload 3.93.0"

# 5. En producción: detener app, aplicar migraciones, reiniciar
docker compose run --rm app npx payload migrate
docker compose up -d app

Nunca edites manualmente una migración de src/migrations/ ya aplicada: Payload registra cada migración ejecutada por su nombre en la colección payload-migrations y no la vuelve a ejecutar, así que el cambio nunca llega a producción. Escribe una nueva migración en su lugar. Para deshacer una migración: npx payload migrate:down.

Es el obstáculo más común al desplegar en un VPS, y se presenta en tres formas distintas. La más desconcertante es Unsupported CPU: Prebuilt binaries for Linux x64 require v2 microarchitecture («linux-x64» antes de sharp 0.35): no viene de tu código ni de tus dependencias, sino del procesador de la máquina. Los binarios precompilados apuntan a un conjunto de instrucciones que las CPU más antiguas no exponen — es un criterio de selección de VPS, no un bug. La segunda, Could not load the "sharp" module using the linux-x64 runtime, casi siempre indica un node_modules construido en otra plataforma — reinstala en la máquina objetivo. La tercera es propia de Docker multi-stage: sharp instalado en la etapa de construcción pero ausente de la etapa de ejecución — instálalo explícitamente en la etapa final.

Build OOM — Killed o JavaScript heap out of memory.
Ocurre durante npm run build cuando el VPS va justo de RAM y el heap de Node.js alcanza su límite. Establece NODE_OPTIONS=--max-old-space-size=3072 en el entorno antes del build, o construye la imagen en una máquina más potente y súbela a un registry.

PostgreSQL — Error: connect ECONNREFUSED 127.0.0.1:5432.
La app intenta conectarse antes de que PostgreSQL esté listo, o la URL de conexión apunta a localhost en lugar del nombre del servicio Docker (postgres). Verifica que DATABASE_URI use el nombre del servicio y que el healthcheck esté configurado (ver paso 3).

Admin inaccesible en prod — /admin devuelve 404 o redirección en bucle.
Dos causas principales: serverURL no definido o no coincidente con la URL real, o la cabecera X-Forwarded-Proto: https ausente del proxy Nginx. Añade proxy_set_header X-Forwarded-Proto $scheme; al vhost y verifica que serverURL coincida exactamente con el origen público, sin barra diagonal final.

CORS — Access-Control-Allow-Origin ausente en la API.
Payload lee cors desde payload.config.ts. En producción, lista explícitamente los orígenes autorizados: cors: { origins: ['https://example.com'] }. cors: { origins: [serverURL] } es la configuración mínima segura.

Una migración retocada no se aplica.
Un archivo en src/migrations/ se editó después de haberse aplicado. Payload registra cada migración ejecutada por su nombre y nunca la vuelve a ejecutar: el cambio se ignora sin ningún error. Restaura el original desde Git, genera un nuevo archivo de migración si el esquema cambió, y aplícalo.