Déployer Strapi sur un VPS : le guide complet

Strapi Cloud ou auto-hébergement : ce que vous perdez, ce que vous gagnez

Bénéfices de l'auto-hébergement de Strapi sur un VPS

• Propriété des données — votre base PostgreSQL et vos uploads restent sur votre VPS, sous votre contrôle exclusif
• Aucun quota de plan — le nombre d'entrées, de types de contenu et de comptes admin n'est plus fixé par un abonnement, mais par les ressources de votre VPS
• Plugins communautaires — tout plugin npm s'installe librement, sans validation ni liste blanche de la plateforme
• API sur votre domaine — REST et GraphQL exposés sur cms.mondomaine.com, sans intermédiaire ni limite de débit imposée
• Pile unifiée — Strapi et un frontend Nuxt ou Next.js cohabitent sur le même VPS, derrière un reverse proxy unique
• Localisation des données — essentielle pour la conformité RGPD et les exigences contractuelles de vos clients
• Coût prévisible — le VPS a un tarif fixe mensuel, indépendant du volume de contenu ou du trafic API
• Contrôle des migrations — vous choisissez quand et comment appliquer les mises à jour de Strapi

Prérequis : matériel, logiciels et domaine

Préparer le projet avant de toucher au serveur

1. 01

   Générer le projet Strapi

   Sur votre poste, générez le projet avec la commande officielle npx create-strapi-app@latest mon-cms --dbclient=postgres. Choisissez TypeScript si votre équipe le maîtrise. Initialisez le dépôt Git, poussez-le sur votre forge, puis clonez-le sur le VPS dans /srv/mon-cms. Tout ce qui suit se prépare dans ce dépôt et non sur le serveur : le VPS ne doit recevoir que du code déjà versionné.

2. 02

   Brancher la configuration de base de données sur PostgreSQL

   Dans config/database.js — ou config/database.ts en TypeScript —, la fonction exportée reçoit env et renvoie un objet connection. Déclarez client: 'postgres', puis six clés lues depuis l'environnement dans le sous-objet connection : host: env('DATABASE_HOST', '127.0.0.1'), port: env.int('DATABASE_PORT', 5432), database: env('DATABASE_NAME', 'strapi'), user: env('DATABASE_USERNAME', 'strapi'), password: env('DATABASE_PASSWORD', '') et ssl: env.bool('DATABASE_SSL', false). Le second argument de env() n'est qu'un repli de développement : aucune valeur réelle ne doit figurer dans ce fichier, il part dans Git.

3. 03

   Générer les cinq secrets de production

   Strapi refuse de démarrer en production sans APP_KEYS, API_TOKEN_SALT, ADMIN_JWT_SECRET, JWT_SECRET et TRANSFER_TOKEN_SALT. Générez chacun avec openssl rand -base64 32 ; APP_KEYS en attend plusieurs, séparées par des virgules, donc produisez-en au moins deux. Écrivez-les dans /srv/mon-cms/.env sur le VPS — jamais dans Git — avec DATABASE_HOST, DATABASE_NAME, DATABASE_USERNAME, DATABASE_PASSWORD, NODE_ENV=production et URL=https://cms.mondomaine.com. Une clé manquante se traduit par un refus de démarrage, pas par un avertissement.

4. 04

   Écrire le Dockerfile multi-étages

   Deux étages suffisent à garder l'image de production légère. L'étage builder part de node:20-alpine, fixe WORKDIR /app, copie package*.json, lance npm ci, copie le reste du code, puis compile l'admin avec NODE_ENV=production npm run build. L'étage runner repart de la même image de base et ne recopie du builder que trois choses : le dossier de build, node_modules et package.json. Terminez par EXPOSE 1337 et un CMD qui appelle npm run start — c'est le script de démarrage que Strapi installe, n'essayez pas de lancer un fichier serveur à la main. Si le build meurt en OOM, posez NODE_OPTIONS=--max-old-space-size=4096 avant npm run build.

Déployer la pile sur le VPS

1. 05

   Décrire les services dans docker-compose.yml

   Le fichier déclare deux services et un volume nommé. Le service postgres utilise l'image postgres:16-alpine, reçoit POSTGRES_DB, POSTGRES_USER et POSTGRES_PASSWORD dans son bloc environment, monte le volume pgdata sur /var/lib/postgresql/data et passe en restart: unless-stopped. Le service strapi se construit depuis le Dockerfile local avec build: ., lit ses variables par env_file: .env, déclare depends_on: postgres, monte ./public/uploads sur /app/public/uploads et publie son port avec ports: 127.0.0.1:1337:1337. Cette liaison sur la boucle locale est le point important : Nginx devient le seul point d'entrée public, le port 1337 n'est jamais exposé à l'extérieur. Un service redis reste optionnel, pour le cache de sessions ou les files de traitement.

2. 06

   Construire l'image et démarrer la pile

   Lancez docker compose build, puis docker compose up -d. Suivez le démarrage avec docker compose logs -f strapi. Strapi applique ses migrations de schéma au premier démarrage dès que NODE_ENV=production est posé. Comptez deux à cinq minutes : la construction de l'admin React est de loin l'étape la plus lente. Attendez la ligne Strapi started successfully avant de continuer.

3. 07

   Placer Nginx en reverse proxy

   Créez le vhost /etc/nginx/sites-available/cms.mondomaine.com. Il écoute en listen 80 sur server_name cms.mondomaine.com, porte un client_max_body_size 50M — indispensable pour les uploads de médias — et un unique bloc location / qui fait proxy_pass http://127.0.0.1:1337. Ajoutez-y les quatre en-têtes que Strapi attend derrière un proxy : Host, X-Real-IP, X-Forwarded-For et X-Forwarded-Proto, chacun posé par une directive proxy_set_header. Activez le vhost par un lien symbolique vers sites-enabled, puis validez et rechargez avec nginx -t && systemctl reload nginx.

4. 08

   Activer HTTPS et fixer la variable URL

   Obtenez le certificat avec certbot --nginx -d cms.mondomaine.com : Certbot réécrit le vhost pour rediriger HTTP vers HTTPS. Vérifiez ensuite que URL=https://cms.mondomaine.com figure bien dans le .env, sans barre oblique finale. C'est cette variable que Strapi utilise pour construire les liens des médias et les redirections de l'admin ; sans elle, les fichiers téléversés sortent avec des adresses fausses et le panneau d'administration se comporte mal derrière le proxy. Redémarrez le conteneur après toute modification du .env : les variables sont lues au démarrage.

5. 09

   Vérifier que l'instance répond vraiment

   Ouvrez https://cms.mondomaine.com/admin et créez le premier compte administrateur — Strapi le demande au premier accès et ne le redemandera plus. Contrôlez ensuite trois points : docker compose ps montre les deux conteneurs en état running, l'API publique répond sur /api, et l'envoi d'un fichier de test depuis la médiathèque aboutit. Un 502 Bad Gateway à ce stade signale presque toujours un conteneur strapi arrêté ou encore en cours de build : relisez docker compose logs strapi avant de toucher à Nginx.

Sortir les médias du disque : le provider S3

Automatiser la sauvegarde de la base

1. 10

   Créer le dossier de destination

   Sur le VPS, mkdir -p /srv/backups/strapi. Gardez ce dossier hors du dépôt Git et hors de tout chemin monté dans un conteneur : un dump ne doit jamais partir dans une image ni dans une release.

2. 11

   Repérer le nom réel du conteneur PostgreSQL

   docker compose ps donne le nom exact, de la forme mon-cms-postgres-1. Il dérive du nom du dossier de projet : ne le recopiez pas d'un guide, lisez-le sur votre machine. Un script de sauvegarde qui vise un conteneur inexistant échoue en silence une fois placé dans le cron.

3. 12

   Écrire la commande de dump

   Une seule ligne suffit : docker exec mon-cms-postgres-1 pg_dump -U strapi strapi | gzip > /srv/backups/strapi/strapi-$(date +%Y%m%d).sql.gz. Le pg_dump s'exécute dans le conteneur, la compression et l'écriture se font sur l'hôte. Lancez-la une première fois à la main et vérifiez la taille du fichier produit : un dump de quelques octets signale une erreur d'authentification avalée par le tube.

4. 13

   Purger les dumps trop anciens

   Ajoutez à la suite find /srv/backups/strapi -name '*.sql.gz' -mtime +7 -delete. Sans cette ligne, le disque se remplit en quelques semaines : c'est la panne la plus banale d'une sauvegarde quotidienne — la base tombe parce que la sauvegarde a saturé le volume.

5. 14

   Planifier, puis sortir les dumps du serveur

   Placez les deux commandes dans un script /etc/cron.daily/strapi-backup, avec #!/bin/bash en première ligne et un chmod +x pour le rendre exécutable. Ajoutez-y un rsync vers un stockage externe, ou un envoi vers le même bucket S3 que les médias. Une sauvegarde qui reste sur la machine qu'elle sauvegarde ne protège de rien ; testez une restauration complète au moins une fois avant d'en dépendre.

Mettre à jour Strapi sans casser les migrations

Dépannage : les erreurs les plus fréquentes

Strapi et un frontend Nuxt ou Next.js sur le même VPS