Déployer une application Next.js sur un VPS : procédure vérifiable

Déployer Next.js sur un VPS revient à livrer une application Node avec un build reproductible, un processus géré et une configuration distincte de votre poste. Ne commencez pas par copier le dossier entier sur le serveur. Préparez une version identifiable, installez uniquement les dépendances de production, vérifiez l’application localement sur le VPS, puis placez-la derrière le reverse proxy déjà configuré.

Ce tutoriel traite le déploiement applicatif. Le choix Vercel ou VPS est abordé dans le comparatif dédié, et la configuration détaillée de HTTPS dans le guide TLS. Ici, l’objectif est de savoir quelle version tourne, avec quelles variables, et comment revenir à la version précédente si un contrôle échoue.

Ce que vous allez apprendre

Vous allez préparer un artefact Next.js, créer un compte de service, passer les variables de production sans les committer, démarrer le processus avec un gestionnaire adapté, vérifier la route de santé et réaliser un rollback simple. Vous ne devez pas exposer le port Node directement au public : le proxy reste le point d’entrée prévu.

Prérequis

• Un VPS maintenu, avec un compte applicatif non administrateur.
• Une version Node compatible avec la version Next.js du projet.
• Un dépôt ou un artefact dont le commit de départ est identifié.
• Les variables de production documentées, sans leurs valeurs dans Git.
• Un reverse proxy fonctionnel et une sauvegarde des données externes du projet.

La documentation Next.js doit être votre référence pour la version installée. Ne mélangez pas une commande d’un ancien guide avec un runtime récent sans tester le build et le démarrage.

1. Préparer une version reproductible

Choisissez un commit ou un tag à déployer et enregistrez son identifiant dans votre journal de livraison. Installez les dépendances avec le gestionnaire de paquets prévu par le projet et utilisez le lockfile. Lancez les contrôles déjà définis par le dépôt avant la livraison. Un build qui réussit sur votre poste ne suffit pas si la version Node, les variables ou le système du VPS diffèrent.

Préparez un artefact ou un checkout propre qui contient le code, le lockfile et les fichiers nécessaires au runtime, mais pas les caches, les secrets ou les fichiers de développement inutiles. Si votre projet utilise la sortie standalone de Next.js, vérifiez dans la documentation et les fichiers générés qu’elle est bien adaptée à votre configuration ; ne présumez pas qu’elle couvre toutes les ressources ou tous les chemins statiques.

Vérification : notez le commit, la version Node et la version de Next.js. Construisez une première fois dans un environnement proche de la production et conservez le résultat du build avec son horodatage.

2. Préparer le compte et les répertoires

Créez ou utilisez un compte applicatif dédié, sans privilèges d’administration. Donnez-lui accès au répertoire de release, à un répertoire de logs contrôlé et, si nécessaire, à un volume de fichiers persistants limité. Ne déployez pas dans le répertoire personnel de l’administrateur et ne donnez pas à Node la possibilité de modifier la configuration système.

Conservez une release précédente identifiée. Un répertoire de versions immuables ou un mécanisme de lien vers la release active rend le rollback plus simple qu’une copie par-dessus la version courante. Les données et migrations restent une responsabilité séparée : revenir au code ne revient pas automatiquement au schéma de base.

Vérification : connectez-vous avec le compte applicatif. Il doit pouvoir lancer l’application dans son répertoire, mais pas lire des secrets d’administration ou utiliser sudo.

3. Injecter les variables de production

Listez les variables nécessaires, leur propriétaire et l’environnement auquel elles appartiennent. Les clés de base, tokens de services ou URL privées ne doivent ni apparaître dans le dépôt ni être affichés par une commande de diagnostic. Utilisez le mécanisme de secrets ou d’environnement de votre système d’exploitation et donnez au processus seulement les variables dont il a besoin.

Vérifiez aussi les URLs publiques : un domaine de production erroné peut casser les redirections, les canoniques ou les callbacks sans empêcher le processus de démarrer. Gardez une configuration de test séparée afin de ne pas envoyer d’email, de webhook ou d’écriture métier lors d’une restauration.

Vérification : démarrez le processus avec une variable volontairement absente dans un environnement de test. L’échec doit être clair et ne doit pas imprimer de secret. Ajoutez ensuite la valeur par le canal prévu et vérifiez uniquement le comportement fonctionnel attendu.

4. Démarrer et superviser le processus

Utilisez un gestionnaire de processus ou un service système qui redémarre le processus de manière contrôlée et écrit des journaux accessibles à l’exploitation. Définissez l’utilisateur, le répertoire de travail, la commande de démarrage, les variables autorisées et une politique de redémarrage. Évitez les boucles de redémarrage qui masquent une erreur de configuration et épuisent les ressources.

L’application doit écouter sur une interface interne si le reverse proxy est son point d’accès public. Le proxy transmet ensuite les requêtes HTTPS vers ce backend. Cette séparation réduit la surface exposée et facilite le contrôle des en-têtes, certificats et limitations réseau sans réimplémenter ces règles dans l’application.

Vérification : consultez l’état du service, appelez la route de santé depuis le VPS, puis passez par le domaine public. Les deux vérifications servent à distinguer une panne d’application d’une panne de proxy.

5. Livrer puis valider avant de basculer

Avant de rendre une release active, vérifiez sa configuration, son build et ses dépendances. Basculez selon votre mécanisme de release, rechargez le service de façon contrôlée et exécutez un smoke test : page principale, route critique, authentification de test si elle existe, et journaux d’erreur. Surveillez les premières minutes : une page 200 ne prouve pas qu’une API ou une tâche de fond fonctionne.

Ne faites pas coïncider automatiquement déploiement applicatif et migration destructive de base. Les migrations exigent leur propre verrou, sauvegarde et vérification. Si elles sont incompatibles avec la release précédente, le rollback doit être planifié avant l’exécution.

Vérification : consignez la release active, la route testée, le résultat et l’heure. Comparez les erreurs et la latence avant et après, sans inclure de données sensibles dans le compte rendu.

6. Préparer le retour arrière

Un rollback n’est pas une décision improvisée. Gardez la release précédente, le mode de bascule et les variables qui lui correspondent. Définissez les seuils d’arrêt : erreurs répétées, route critique indisponible, fuite de mémoire ou régression fonctionnelle confirmée. Si les données ont changé, appliquez la procédure dédiée plutôt que de revenir au code en espérant réparer le schéma.

Vérification : sur un environnement de test, basculez vers une release précédente puis vérifiez l’état du service et une route fonctionnelle. Ce test transforme une instruction de rollback en capacité réelle.

Problèmes fréquents et solutions

Le build passe mais le service ne démarre pas. Comparez version Node, variables, permissions et répertoire de travail. Ne corrigez pas par un lancement root.

La page publique renvoie 502. Vérifiez d’abord le backend local puis la cible du proxy. Un certificat valide n’indique pas que l’application Node est en écoute.

Une release casse une route secondaire. Gardez un smoke test couvrant les parcours critiques et un rollback vérifié ; ne vous fiez pas à la page d’accueil seule.

Les secrets apparaissent dans les logs. Retirez-les, révoquez-les si nécessaire et modifiez la journalisation. Un filtre ajouté après exposition ne rend pas une clé sûre.

FAQ

Faut-il utiliser un gestionnaire de processus ?

Un mécanisme de supervision est recommandé pour connaître l’état du service, redémarrer de façon contrôlée et consulter les logs. Le choix exact dépend du système d’exploitation et de l’exploitation existante.

Doit-on exposer le port Next.js ?

En général non : gardez le processus derrière un reverse proxy qui gère l’entrée publique et HTTPS.

Peut-on déployer avec Git sur le VPS ?

Oui, si le checkout, les clés et les permissions sont maîtrisés. Un artefact construit ailleurs peut aussi réduire les opérations sur le serveur. Dans les deux cas, identifiez la release.

Comment gérer les migrations ?

Comme une étape séparée, sauvegardée et contrôlée. Ne les déclenchez pas implicitement à chaque démarrage de l’application.

Quelle est la première alerte à ajouter ?

Commencez par l’indisponibilité de la route de santé et les redémarrages anormaux du service, puis ajoutez espace disque et erreurs applicatives.

Conclusion

Déployer une app Next.js sur un VPS est robuste lorsque chaque release est identifiable, exécutée par un compte limité, configurée sans secret dans Git et vérifiée avant bascule. Le proxy, les sauvegardes et le rollback ne sont pas des détails après coup : ils permettent de livrer sans perdre la maîtrise du service.

Pour comparer le VPS aux autres approches de déploiement, consultez le comparatif des hébergeurs français.

Sources et limites

Sources primaires : Next.js deployment, Next.js self-hosting et Node.js security best practices. Les commandes de service et de proxy dépendent de votre distribution. Ce guide ne remplace pas les tests du dépôt ou la procédure de migration de votre application.