Déployer Payload CMS sur VPS : guide complet

Payload CMS adopte une approche radicalement code-first : votre schéma de contenu est défini en TypeScript dans des fichiers de configuration, versionnés avec Git, et depuis sa version 3 Payload s'installe directement dans une application Next.js via le App Router. Cela signifie qu'un VPS vous permet d'héberger le CMS et le site front dans un seul et même processus Node, partageant le build et le runtime. Vous obtenez un typage de bout en bout, des migrations de schéma gérées dans le code, et aucune dépendance à une interface graphique pour modéliser vos contenus. Le self-hosting est ici l'option naturelle : Payload est pensé pour être déployé comme n'importe quelle app Next.js, et un VPS vous donne le contrôle de la base (MongoDB ou PostgreSQL), des uploads et des variables d'environnement, sans plateforme intermédiaire.

Payload reposant sur Next.js, le build est exigeant : prévoyez un VPS de 2 vCPU et 4 Go de RAM pour builder et faire tourner l'application confortablement, surtout si le front Next.js est conséquent. Installez Node.js 20 LTS, Docker et Docker Compose. Côté base, provisionnez MongoDB 7 ou PostgreSQL 16 selon l'adaptateur choisi (@payloadcms/db-mongodb ou @payloadcms/db-postgres). Pointez votre domaine vers l'IP du VPS. Comptez 15 Go de disque pour les node_modules, le build .next, les uploads et les sauvegardes de base.

Payload 3 gère les utilisateurs via la collection users définie dans payload.config.ts. Activez l'authentification sur la collection avec le champ auth: true — cela ajoute automatiquement les endpoints /api/users/login, /api/users/logout, /api/users/me et /api/users/refresh-token.

Pour les rôles, Payload n'impose pas de modèle : vous définissez un champ role (type select) sur la collection users, puis vous pilotez les accès via les fonctions access au niveau de chaque collection et de chaque opération :

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

Pour les accès programmatiques (CI, intégrations tierces), utilisez les API keys : activez useAPIKey: true dans la config d'authentification de la collection. Chaque utilisateur peut alors générer une clé depuis le panneau admin. Transmettez-la dans l'en-tête Authorization: users API-Key votre-cle. Les API keys sont hachées en base — une clé perdue ne se récupère pas, elle se régénère.

Les collection hooks de Payload 3 permettent d'exécuter du code avant ou après chaque opération CRUD. Ils remplacent avantageusement les webhooks quand la logique vit dans le même runtime :

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

Les hooks disponibles sont beforeOperation, beforeValidate, beforeChange, afterChange, beforeRead, afterRead, beforeDelete et afterDelete. Un hook afterChange est idéal pour invalider un cache CDN, envoyer une notification ou synchroniser avec un service externe après publication.

Pour les webhooks HTTP sortants (notifier un site statique, un Slack, un pipeline de build), Payload ne fournit pas de module dédié mais les hooks afterChange suffisent : un simple fetch vers votre endpoint cible à l'intérieur du hook remplit ce rôle. Veillez à ne pas bloquer la réponse sur une requête externe — wrappez l'appel dans un setImmediate ou un processus séparé si la latence est un critère.

Payload 3 suit le versionnement sémantique. Les mises à jour de patch (3.x.y → 3.x.z) sont sûres à appliquer sans migration. Les mises à jour mineures (3.x → 3.y) peuvent ajouter des colonnes ou des index et nécessitent de rejouer payload migrate.

Workflow recommandé pour chaque mise à jour :

# 1. Bumper la version dans package.json
npm install [email protected] @payloadcms/[email protected]

# 2. Générer le fichier de migration si le schéma a changé
npx payload migrate:create

# 3. Tester en local sur une copie de la base
npx payload migrate

# 4. Committer le fichier de migration avec le bump de version
git add src/migrations/ package.json package-lock.json
git commit -m "chore: payload 3.88.0"

# 5. En production : arrêter l'app, appliquer les migrations, redémarrer
docker compose run --rm app npx payload migrate
docker compose up -d app

Ne jamais modifier à la main les fichiers générés dans src/migrations/ : Payload les vérifie par hash. Un fichier retouché fait échouer migrate avec Error: Migration file has been modified since it was created. Pour revenir en arrière sur une migration : npx payload migrate:down.

C'est le premier obstacle du déploiement sur VPS, et il prend trois formes distinctes qu'il vaut mieux savoir distinguer. La plus déroutante est Unsupported CPU: prebuilt binaries for linux-x64 require v2 microarchitecture : elle ne vient ni de votre code ni de vos dépendances, mais du processeur de la machine. Les binaires précompilés visent un jeu d'instructions que les CPU les plus anciens n'exposent pas — c'est donc un critère de choix de VPS, pas un bug à corriger. La deuxième, Could not load the "sharp" module using the linux-x64 runtime, signale presque toujours un node_modules fabriqué sur une autre plateforme, typiquement un macOS de développement copié vers un serveur Linux : réinstallez sur la machine cible plutôt que de transporter le dossier. La troisième est propre à Docker multi-étapes : sharp installé dans l'étape de construction seulement, absent de l'étape d'exécution — le conteneur démarre puis échoue au premier traitement d'image. Installez-le explicitement dans l'étape finale. Sur une architecture ARM, la même vigilance s'applique : la bibliothèque doit être résolue pour cette plateforme.

Build OOM — Killed ou JavaScript heap out of memory.
Survient pendant npm run build quand la RAM disponible est inférieure à 3 Go. Node.js est limité à ~1,8 Go par défaut. Passez NODE_OPTIONS=--max-old-space-size=3072 dans l'environnement avant de lancer le build, ou buildez l'image sur une machine plus puissante et poussez l'image vers un registry.

PostgreSQL — Error: connect ECONNREFUSED 127.0.0.1:5432.
L'app tente de se connecter avant que PostgreSQL soit prêt, ou l'URL de connexion pointe sur localhost au lieu du nom du service Docker (postgres). Vérifiez que DATABASE_URI utilise le nom du service (postgresql://payload:pass@postgres:5432/payload) et que le healthcheck est en place (voir étape 3).

Admin inaccessible en prod — /admin répond 404 ou redirige en boucle.
Deux causes principales : serverURL non défini ou non correspondant à l'URL réelle (Payload génère ses redirections internes depuis cette valeur), ou le header X-Forwarded-Proto: https absent du reverse proxy Nginx. Ajoutez proxy_set_header X-Forwarded-Proto $scheme; dans le vhost et vérifiez que serverURL est identique à l'origine publique, sans barre oblique finale.

CORS — Access-Control-Allow-Origin manquant sur l'API.
Payload lit cors depuis payload.config.ts. En production, listez explicitement vos origines autorisées : cors: { origins: ['https://example.com'] }. Laisser cors: '*' accepte toutes les origines, ce qui peut être voulu pour une API publique mais expose l'admin aux requêtes cross-origin. cors: { origins: [serverURL] } est le réglage minimal sûr.

Error: Migration file has been modified since it was created.
Un fichier dans src/migrations/ a été édité manuellement après sa génération. Payload vérifie l'intégrité de chaque fichier. Restaurez l'original depuis Git, générez un nouveau fichier de migration si le schéma a changé, et réappliquez dans l'ordre.