Aller au contenu

Ingénierie · DevOps

Next.js · Strapi 5 · Cloudflare : notes de production L’architecture auto-hébergée que nous exploitons, et le piège de cache qui masquait nos mises en ligne

Nous exploitons Next.js et Strapi 5 sur un serveur Linux que nous administrons : PostgreSQL pour les données, pm2 pour garder chaque application compilée en marche en mode production, nginx devant, Cloudflare en bordure. Coûts et données restent maîtrisés, à condition de régler le cache du HTML : Next.js laisse les caches partagés garder un an les pages pré-rendues.

Auteur
Wael ChabchoubiFondateur & Tech Lead
Publié le
Mis à jour le
Lecture
12 minRead in English

À quoi ressemble une architecture Next.js et Strapi auto-hébergée ?

Cinq couches, chacune avec un rôle. Cloudflare gère le DNS, le TLS et la bordure. nginx porte le certificat d’origine et envoie chaque domaine vers un port local. Next.js rend le site, Strapi sert l’API et l’interface d’administration, PostgreSQL stocke les données. Tout, sauf Cloudflare, tourne sur un serveur Linux que nous exploitons.

C’est l’architecture des systèmes que nous développons et exploitons pour des clients comme TSS Company, dont l’ERP repose sur Strapi 5, Next.js 16 et PostgreSQL. Son front et son API vivent sur deux sous-domaines, chacun avec son hôte virtuel nginx, et chaque processus n’écoute que sur 127.0.0.1 : nginx est la seule porte d’entrée. Le site que vous lisez reprend les mêmes couches de bordure, de proxy et de processus, sans Strapi.

Notre pile de production Next.js + Strapi, octobre 2026
CoucheCe que nous utilisonsPourquoiPoint de vigilance
BordureProxy Cloudflare, certificat d’origine, TLS Full (strict)DNS, TLS et protection au même endroitRègles de cache du HTML ; Cloudflare peut aussi injecter des scripts dans le HTML
Proxy inversenginx, un hôte virtuel par domaineEnvoie chaque domaine vers un port local, pose les en-têtesUn seul add_header dans une location fait perdre ceux du serveur
FrontNext.js 16 (App Router) avec next startRendu serveur et pages pré-renduesLe Cache-Control des pages pré-rendues
API et administrationStrapi 5 avec strapi startTypes de contenu, rôles, API REST, interface d’administrationIl exécute le dossier dist compilé, pas src
Base de donnéesPostgreSQL, une base et un rôle par applicationDonnées relationnelles, montants en numeric exactTaille du pool sur un cluster partagé
Processuspm2 en mode fork, limite mémoire, liste sauvegardéeRedémarrage après un plantage ou un rebootJamais de serveur de développement en production

Rien d’exotique, et c’est voulu : chaque couche est documentée, gratuite et remplaçable. La suite détaille ce qui nous a coûté du temps sur de vrais déploiements, pour que cela ne vous en coûte pas.

Pourquoi héberger nous-mêmes plutôt que sur une plateforme managée ?

Parce que nos clients font tourner des logiciels de gestion, pas des médias mondiaux. Un ERP ou un catalogue B2B sert un public connu, surtout en Tunisie, et gagne davantage à garder ses données sous contrôle avec une facture prévisible qu’à être rendu dans de nombreuses régions. Et nous voulons exploiter ce que nous livrons, de bout en bout.

L’auto-hébergement n’est pas gratuit en travail : il faut appliquer les mises à jour, surveiller la mémoire et le disque, renouveler les certificats, tester les sauvegardes et réagir quand un processus tombe. Nous le faisons dans le cadre de notre service DevOps et hébergement. Si personne ne peut porter ces tâches, ni chez vous ni chez un prestataire, une plateforme managée reste le choix prudent ; la dernière section dit quand.

Comment garder Next.js et Strapi en marche en production ?

Chaque application est compilée une fois, puis lancée en mode production sous pm2, un gestionnaire de processus Node.js. pm2 relance un processus qui plante ou dépasse sa limite mémoire, et sa liste sauvegardée survit au redémarrage du serveur. Un serveur de développement ne sert jamais le trafic réel, même pour une correction rapide.

Nous avons appris cette dernière règle à nos dépens. Sur un serveur partagé, un serveur de développement Next.js lancé à la main pour une vérification est resté actif. Il a atteint 3,76 Go de mémoire, le noyau Linux l’a tué faute de mémoire, et comme aucun superviseur ne le connaissait, rien ne l’a relancé. En mode production, le même front tient dans environ 70 Mo.

Voici le type de fichier pm2 que nous utilisons pour un front-end Next.js, simplifié :

module.exports = {
  apps: [
    {
      name: 'site-front',
      script: 'node_modules/next/dist/bin/next',
      args: 'start -H 127.0.0.1 -p 3000',   // localhost only: nginx is the front door
      node_args: '--max-old-space-size=384', // heap cap for this app
      max_memory_restart: '600M',            // pm2 restarts it above this
      exec_mode: 'fork',
      autorestart: true,
      env: { NODE_ENV: 'production', NEXT_TELEMETRY_DISABLED: '1' },
    },
  ],
};
js · ecosystem.config.js pour une application Next.js. Démarrage : pm2 start ecosystem.config.js, puis pm2 save.

La compilation demande la même discipline. Plusieurs applications Node.js partagent nos serveurs, et un next build sans plafond peut consommer assez de mémoire pour ralentir ou arrêter ses voisins. Nous compilons toujours avec NODE_OPTIONS=--max-old-space-size=1536 et ne redémarrons que l’application concernée, jamais tous les processus d’un coup.

Strapi ajoute son propre piège : strapi start exécute le dossier compilé dist/, pas vos sources. Après une modification dans src/, il faut compiler puis redémarrer. Une simple vérification de types ne change rien à ce qui tourne ; un correctif de démarrage est déjà resté sans effet chez nous pour cette seule raison.

Quels comportements de Strapi 5 connaître avant la mise en ligne ?

Six comportements de Strapi 5 nous ont coûté du temps sur de vrais projets : des hooks qui ne voient pas les composants, le documentId dans les URL, des brouillons invisibles pour l’API, des montants arrondis à deux décimales dans PostgreSQL, des en-têtes CORS en double et les limites négatives. Chacun se corrige simplement, une fois connu.

  • Hooks et composants. Strapi 5 enregistre les composants, par exemple les lignes d’une facture, avant l’exécution de beforeCreate : le hook ne voit que des références, pas les valeurs. Nous calculons les totaux du document dans le contrôleur, qui reçoit le corps brut de la requête, et nous plaçons les effets de bord (mouvements de stock, soldes clients) dans afterCreate et afterUpdate.
  • documentId, pas id. L’API REST désigne les entrées par documentId. Les id numériques restent acceptés pour écrire une relation : un code qui mélange les deux se trompe facilement. Voir la documentation du Document Service (nouvel onglet).
  • Brouillons et publication. Sur un type avec Draft & Publish (nouvel onglet), strapi.documents().create() sans status: 'published' crée un brouillon, que l’API REST ne renvoie pas par défaut. Les listes restent vides et rien n’a l’air cassé.
  • Montants et décimales. Sur une application de facturation que nous avons déployée, les champs décimaux sont sortis en numeric(10,2) dans PostgreSQL : 14,875 devenait 14,88. Or le dinar compte trois décimales, les millimes. Nous avons migré 52 colonnes en numeric(14,3) ; tout champ décimal ajouté ensuite exige sa propre migration.
  • CORS entre deux sous-domaines. Laissez Strapi poser les en-têtes CORS. Si nginx ajoute aussi Access-Control-Allow-Origin, le navigateur reçoit deux valeurs et rejette la réponse. Les fichiers sont concernés : un export PDF qui dessine le logo de l’entreprise dans le navigateur a besoin de ces en-têtes sur /uploads.
  • Limites négatives. strapi.db.query().findMany({ limit: -1 }) échoue sur PostgreSQL (LIMIT must not be negative). Le Document Service le tolère ; avec le Query Engine, omettez simplement la limite.

Pourquoi Cloudflare servait-il encore les anciennes pages après une mise en ligne ?

Next.js envoie s-maxage=31536000 sur les pages pré-rendues, ce qui autorise les caches partagés à les garder un an. Sur l’un de nos déploiements derrière Cloudflare, les visiteurs ont reçu l’ancien HTML pendant des semaines, et ce HTML appelait des fichiers JavaScript que notre serveur avait déjà supprimés. L’en-tête de réponse indiquait pourtant DYNAMIC.

La documentation de Next.js (nouvel onglet) est claire : une page statique sans revalidation reçoit s-maxage=31536000, soit un an, et les fichiers hachés de /_next/static/ reçoivent public, max-age=31536000, immutable. Cloudflare ne met pas le HTML en cache par défaut (nouvel onglet), mais sa documentation sur Cache-Control (nouvel onglet) rappelle que s-maxage régit les caches partagés et que les offres Free, Pro et Business suivent l’en-tête de l’origine par défaut. Dès que le HTML est mis en cache en bordure, un en-tête d’un an devient une page figée un an.

Deux détails rendaient le problème difficile à voir. Les scripts appelés par l’ancien HTML répondaient 404 sur notre serveur, mais se chargeaient via Cloudflare, qui les avait gardés eux aussi. Et la réponse HTML portait cf-cache-status: DYNAMIC, qui se lit « pas en cache ». Ne vous fiez pas à cet en-tête seul.

Le diagnostic en trois commandes

Comparez ce que sert l’origine avec ce que renvoie l’URL publique, puis ajoutez un paramètre anti-cache. Si l’URL publique simple diffère de l’origine et que l’URL avec paramètre lui est identique, un cache s’est glissé entre les deux.

# 1. Ce que sert l'origine (Cloudflare contourné)
curl -s http://127.0.0.1:3007/ -H "Host: www.exemple.tn" \
  | grep -o '/_next/static/chunks/[^"]*' | sort -u | head -3

# 2. Ce que reçoivent les visiteurs
curl -s https://www.exemple.tn/ \
  | grep -o '/_next/static/chunks/[^"]*' | sort -u | head -3

# 3. La même page avec un paramètre anti-cache
curl -s "https://www.exemple.tn/?v=$(date +%s)" \
  | grep -o '/_next/static/chunks/[^"]*' | sort -u | head -3
bash · Noms de fichiers différents entre 1 et 2, identiques entre 1 et 3 : le HTML est en cache entre l’origine et le visiteur.

Comment avons-nous corrigé le problème durablement ?

Le HTML se revalide à chaque requête, les fichiers hachés restent immuables, les fichiers statiques sont versionnés par un identifiant de déploiement, et le cache Cloudflare a été purgé une fois. Le nouvel en-tête empêche de nouvelles copies périmées ; seule la purge efface celles déjà stockées. Ce site envoie public, max-age=0, must-revalidate.

  1. Le HTML doit se revalider. Sur l’application touchée, nginx remplace l’en-tête : proxy_hide_header Cache-Control, puis add_header Cache-Control "private, no-cache, no-store, must-revalidate" sur location /. Ce site fixe public, max-age=0, must-revalidate dans next.config.ts, et nginx applique la même règle.
  2. Les fichiers hachés restent immuables. /_next/static/ garde public, max-age=31536000, immutable : leurs noms changent à chaque compilation, un cache long est donc sans risque.
  3. Versionner la compilation. Nous renseignons `deploymentId` (nouvel onglet) via NEXT_DEPLOYMENT_ID, alimenté par le hash du commit. Next.js ajoute ?dpl= aux URL des fichiers statiques et s’en sert pour détecter le décalage de versions (nouvel onglet) entre un onglet ouvert et un nouveau déploiement.
  4. Purger une fois. Ni le nouvel en-tête ni la nouvelle compilation ne délogent ce que Cloudflare a déjà stocké. Purgez après la correction, puis vérifiez avec un paramètre anti-cache.
// next.config.ts (excerpt)
const revalidate = [{ key: 'Cache-Control', value: 'public, max-age=0, must-revalidate' }];

const nextConfig = {
  deploymentId: process.env.NEXT_DEPLOYMENT_ID || undefined, // commit hash, set at build time
  async headers() {
    return [
      { source: '/:locale(en|fr)', headers: revalidate },
      { source: '/:locale(en|fr)/:path*', headers: revalidate },
    ];
  },
};
ts · Les en-têtes de cache de ait-tun.com, tels quels.

Le détail nginx qui nous a fait perdre nos en-têtes de sécurité

La correction du cache a révélé un second piège. Dans nginx, dès qu’un bloc location contient un seul add_header, il n’hérite plus d’aucun add_header du bloc server. Une location ajoutée pour fixer Cache-Control perd sans bruit HSTS, X-Content-Type-Options, Referrer-Policy et la politique de sécurité du contenu. Le suffixe always n’y change rien : il ne concerne que les codes de réponse. La documentation de nginx (nouvel onglet) énonce la règle, et les versions récentes (1.29.3 et suivantes) ajoutent une directive add_header_inherit. Nous gardons les en-têtes de sécurité dans un fichier inclus dans chaque location.

location / {
    proxy_pass http://127.0.0.1:3007;
    proxy_hide_header Cache-Control;
    include snippets/security-headers.conf;   # re-declared: add_header is not inherited here
    add_header Cache-Control "private, no-cache, no-store, must-revalidate" always;
}
nginx · Hôte virtuel simplifié : le HTML se revalide et les en-têtes de sécurité sont redéclarés.

À quoi ressemble une mise en production, étape par étape ?

Cinq étapes, toujours dans le même ordre : compiler avec un plafond mémoire et le hash du commit comme identifiant, redémarrer le seul processus concerné, vérifier l’origine en direct, vérifier l’URL publique avec un paramètre anti-cache, puis purger Cloudflare si le HTML a pu être mis en cache. Sauter la dernière vérification laisse survivre les pages périmées.

  1. NEXT_DEPLOYMENT_ID=$(git rev-parse --short HEAD) NODE_OPTIONS=--max-old-space-size=1536 npx next build pour le front, npm run build pour Strapi.
  2. pm2 restart <app> pour cette application seulement, jamais pm2 restart all sur un serveur partagé.
  3. curl -sI http://127.0.0.1:<port>/ pour confirmer que l’origine répond avec le bon Cache-Control.
  4. curl -sI "https://<domaine>/?v=$RANDOM" pour voir ce que renvoie la bordure maintenant.
  5. Une purge Cloudflare si une ancienne configuration a pu mettre le HTML en cache.

Next.js 16 nous a-t-il réservé une surprise ?

Une, sur ce site même. Avec next start lié à 127.0.0.1, Next.js 16.4 construisait l’URL de la requête du proxy avec localhost mais comparait les réécritures à 127.0.0.1 : chaque URL française localisée redirigeait vers elle-même. L’option skipProxyUrlNormalize à true dans next.config.ts a supprimé la boucle, et les pages françaises s’affichent normalement.

La boucle n’apparaissait qu’avec le serveur de production lié à 127.0.0.1, c’est-à-dire exactement comme nous faisons tourner chaque application derrière nginx. La leçon dépasse cette option : testez la compilation de production avec la même adresse d’écoute et le même proxy que le serveur réel, avant de basculer le DNS.

Que mettre dans votre liste de contrôle avant la mise en ligne ?

Vérifiez les processus, le cache, les en-têtes, les données et la reprise avant le premier visiteur : processus supervisés en mode production, HTML revalidé, fichiers hachés immuables, en-têtes de sécurité dans chaque location, colonnes monétaires à la bonne précision, restauration testée et purge après la bascule. Chaque ligne découle d’un incident décrit plus haut.

  • Front et API tournent sous pm2 ou systemd en mode production, avec une limite mémoire et une liste de processus sauvegardée.
  • Aucun serveur de développement sur la machine de production : ni next dev, ni strapi develop.
  • Les réponses HTML envoient un Cache-Control qui se revalide ; /_next/static/ reste immuable.
  • deploymentId est alimenté par le hash du commit.
  • Les en-têtes de sécurité sont redéclarés dans chaque location nginx qui ajoute un en-tête.
  • Les en-têtes CORS viennent d’une seule couche.
  • Les colonnes monétaires sont vérifiées dans PostgreSQL (numeric à la bonne échelle), pas seulement dans le schéma Strapi.
  • Les compilations sont plafonnées par NODE_OPTIONS=--max-old-space-size sur un serveur partagé.
  • Les sauvegardes sont planifiées et une restauration a réellement été testée.
  • Cloudflare est purgé après la bascule, puis vérifié avec une URL anti-cache.

Quand cette architecture est-elle un mauvais choix ?

Quand personne ne s’occupera du serveur. L’auto-hébergement remplace une facture de plateforme par du travail d’exploitation : mises à jour, supervision, sauvegardes, incidents. C’est aussi le mauvais outil s’il faut un rendu dans de nombreuses régions, une montée en charge automatique ou une purge du CDN à chaque modification de contenu. Une plateforme managée vaut alors son prix.

Pour l’essentiel des logiciels que nous construisons, un ERP, un CRM, un catalogue ou un SaaS pour un marché connu, ces besoins ne se posent pas, et un serveur bien tenu reste plus simple à maîtriser. Nos pages Next.js et Strapi expliquent où chacun s’impose, et le service applications web et SaaS montre comment nous cadrons un projet. Le vocabulaire est dans le glossaire.

FAQ

Les questions que l’on nous pose

Strapi 5 est-il prêt pour des applications de gestion en production ?

Oui, avec méthode. Nous exploitons Strapi 5 en production derrière Next.js pour des ERP et des sites de contenu. Prévoyez ses particularités : totaux calculés dans les contrôleurs, documentId dans les URL, visibilité des brouillons, précision décimale dans PostgreSQL, compilation avant chaque redémarrage. La plupart des problèmes rencontrés venaient de ces détails, pas de Strapi lui-même.

Faut-il laisser Cloudflare mettre en cache les pages Next.js ?

Seulement en connaissance de cause. Les fichiers hachés de /_next/static/ peuvent rester un an en cache. Le HTML doit se revalider, sauf si vous purgez le cache après chaque mise en ligne et chaque modification de contenu. Next.js marque les pages pré-rendues avec s-maxage=31536000 : toute règle qui cache le HTML peut figer une page un an.

Next.js et Strapi peuvent-ils tourner sur le même serveur ?

Oui. Nous les faisons tourner sur un même serveur Linux, chacun dans son processus pm2 à l’écoute de localhost, derrière nginx avec un hôte virtuel par domaine. Donnez à chaque processus sa limite mémoire, plafonnez la mémoire des compilations et dimensionnez le pool de connexions PostgreSQL selon ce que le cluster partagé supporte.

Sources

Sources et références

Les faits extérieurs cités dans ce guide proviennent de ces documents. Les exemples tirés de nos projets sont de première main.

  1. Using a CDN with Next.js (guide du cache CDN) (nouvel onglet)Next.js documentation · en EN
  2. deploymentId (next.config.js) (nouvel onglet)Next.js documentation · en EN
  3. Self-hosting, dont le décalage de versions (nouvel onglet)Next.js documentation · en EN
  4. Default cache behavior (comportement de cache par défaut) (nouvel onglet)Cloudflare documentation · en EN
  5. Cache-Control et Origin Cache Control (nouvel onglet)Cloudflare documentation · en EN
  6. Module ngx_http_headers_module : add_header (nouvel onglet)nginx documentation · en EN
  7. Document Service API (nouvel onglet)Strapi documentation · en EN
  8. Draft & Publish (nouvel onglet)Strapi documentation · en EN

Envie que cette architecture tourne pour vous ?

Nous développons sur Next.js et Strapi, déployons sur des serveurs que nous exploitons et assurons le suivi après la mise en ligne.