Héberger Next.js sur un VPS avec Node.js, systemd et Nginx

Un site Next.js n’a pas toujours besoin d’un serveur en production. S’il peut exporter du HTML et des fichiers statiques, un serveur web suffit. S’il dépend du rendu à chaque requête, des cookies, des Server Actions ou de routes serveur, il lui faut un runtime compatible. Next.js documente le serveur Node.js, Docker et l’export statique comme des modes de déploiement distincts, avec des capacités différentes.

Ce guide couvre un serveur Node.js autogéré sur VPS. Il ne s’agit pas d’un installateur Next.js en un clic : vous préparez le build, le processus, le proxy, les mises à jour et les sauvegardes.

Vérifier si l’application a besoin d’un serveur

Le guide de déploiement Next.js indique que l’export statique offre moins de fonctionnalités qu’un serveur Node.js ou Docker. C’est la capacité du framework, pas une compatibilité automatique de Hostbrid. Vérifiez le quota de services payants et le fonctionnement des images Docker dans les tarifs Projects actuels. Si vous avez besoin de root et du contrôle du système, comparez les offres VPS.

Examiner le projet avant le déploiement

Vérifiez package.json, le fichier de verrouillage et les scripts réellement utilisés. Une configuration de production courante ressemble à ceci :

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Installez avec le même gestionnaire que celui du lockfile (npm ci, pnpm install --frozen-lockfile ou l’équivalent du projet), compilez et démarrez l’application de production. Le CLI Next.js accepte un hôte et un port ; pour le test local, écoutez seulement sur 127.0.0.1 :

npm ci
npm run build
npm run start -- --hostname 127.0.0.1 --port 3000

Le guide d’installation Next.js actuel indique Node.js 20.9 comme version minimale. Vérifiez les exigences de la version exacte de votre projet et utilisez un runtime compatible. Testez une route avec des données, une route inexistante, next/image, les formulaires, l’authentification et les appels API. Un build réussi ne prouve pas que ces services externes fonctionneront en production.

Garder le serveur actif avec systemd

Sur le VPS, créez un utilisateur Linux sans privilèges administrateur et placez le dépôt dans un répertoire dédié, par exemple /srv/nextjs/app. Compilez à partir du lockfile et conservez les artefacts et dépendances nécessaires à next start. Gardez les secrets hors de Git. Les variables préfixées par NEXT_PUBLIC_ sont incluses dans le JavaScript du navigateur au moment du build ; n’y placez pas de clés privées.

Une unité systemd peut garder l’application active et la redémarrer après une fermeture inattendue :

[Unit]
Description=Next.js application
After=network-online.target
Wants=network-online.target

[Service]
User=nextapp
Group=nextapp
WorkingDirectory=/srv/nextjs/app
Environment=NODE_ENV=production
Environment=PORT=3000
Environment=HOSTNAME=127.0.0.1
EnvironmentFile=/etc/nextjs-app.env
ExecStart=/usr/bin/npm run start -- --hostname 127.0.0.1 --port 3000
Restart=on-failure
RestartSec=5
NoNewPrivileges=true
PrivateTmp=true

[Install]
WantedBy=multi-user.target

Adaptez le chemin absolu de npm à l’installation réelle et limitez l’accès à /etc/nextjs-app.env aux administrateurs. Si l’application utilise des fichiers envoyés, une base de données, des tâches planifiées ou d’autres données, configurez-les et sauvegardez-les séparément ; .next ne remplace pas une sauvegarde des données applicatives.

Placer Nginx devant le serveur et vérifier le domaine

Le guide officiel de self-hosting Next.js recommande un proxy inverse plutôt que d’exposer directement le serveur de l’application. Configurez Nginx pour transmettre le domaine à 127.0.0.1:3000, conserver Host et les en-têtes X-Forwarded-*, et gérez HTTPS avec le certificat du serveur. N’exposez pas le port 3000 à Internet ; n’ouvrez que le proxy et un accès SSH restreint.

Voici un proxy HTTP local minimal ; adaptez les noms de domaine et ajoutez la configuration HTTPS de votre système :

server {
    listen 80;
    server_name example.com www.example.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Depuis l’extérieur du VPS, testez la page d’accueil, une route dynamique, une requête invalide, les fichiers statiques, les journaux et un redémarrage. Next.js conserve une partie de son cache sur disque. Une seule instance peut fonctionner avec un disque local persistant, mais il faut décider comment sauvegarder ou reconstruire ces données. Plusieurs instances exigent une coordination du cache et de la configuration serveur.

Si Next.js ne génère que des fichiers statiques, ne prenez pas en charge un serveur dont l’application n’a pas besoin. Si elle exige SSR et que vous souhaitez gérer Node, Nginx et le système, commencez par le catalogue VPS. Si vous préférez lancer un conteneur comme service et que le forfait offre assez de ressources, consultez Projects et ses limites actuelles. Pour une application Node.js qui n’est pas Next.js, consultez le guide général Node.js.

Sources officielles : déploiement Next.js, self-hosting, configuration requise et options du CLI.