## Une mise à jour de runtime n'est pas une simple commande système Sur un VPS qui héberge plusieurs applications, remplacer le binaire `node` global peut produire une panne en cascade. Un service ancien peut dépendre d'une version précise, un gestionnaire de processus peut conserver un chemin obsolète et une application Next.js peut avoir été compilée avec un runtime différent de celui utilisé au démarrage. La politique officielle des versions Node.js recommande d'ailleurs de réserver la production aux lignes Active LTS ou Maintenance LTS. La méthode la plus sûre consiste à traiter Node.js comme une dépendance de chaque application. On installe une nouvelle version dans un répertoire dédié, on reconstruit uniquement le projet concerné, puis on modifie son service systemd. Les autres applications continuent d'utiliser leur runtime actuel. Installer le nouveau runtime sous un chemin versionné, sans toucher à `/usr/bin/node`. Établir l'état de référence des services, ports, journaux et URL avant la bascule. Conserver l'ancien runtime et la release précédente jusqu'à validation complète. En production, Node.js recommande une version **Active LTS** ou **Maintenance LTS**. Le numéro le plus récent n'est pas automatiquement le meilleur choix : la compatibilité du projet, des modules natifs et du framework reste prioritaire. ## Cartographier l'existant avant de modifier quoi que ce soit Une mise à jour maîtrisée commence par un inventaire. Pour chaque service Node.js, relevez : - le fichier d'unité systemd et son utilisateur d'exécution - le chemin absolu du binaire Node.js réellement lancé - le répertoire de travail, le port et les variables d'environnement - la version utilisée au build et au runtime - l'URL de santé ou, à défaut, une page représentative Les commandes suivantes sont en lecture seule : ~~~bash systemctl list-units --type=service --state=running systemctl cat mon-application.service systemctl show mon-application.service \ -p ExecStart -p Environment -p EnvironmentFiles -p WorkingDirectory readlink -f /proc/$(systemctl show -p MainPID --value mon-application.service)/exe ~~~ Cette dernière vérification est importante. `node --version` dans une session SSH décrit le shell courant, pas nécessairement le processus lancé par systemd. Un service peut très bien utiliser `/opt/node-v22.23.1-linux-x64/bin/node` alors que l'administrateur obtient une autre version dans son terminal. Pour comprendre le rôle du runtime dans la pile, consultez aussi Node.js côté serveur. L'objectif n'est pas seulement de changer une version, mais de conserver une architecture explicite et maintenable. ## Installer un runtime isolé et vérifié Prenons Node.js `v22.23.1` comme exemple concret pour un projet qui impose Node.js 22. Cette version, publiée le 22 juin 2026, appartient à la ligne LTS « Jod ». L'archive Linux x64 officielle possède le SHA-256 suivant : ~~~text 9749e988f437343b7fa832c69ded82a312e41a03116d766797ac14f6f9eee578 ~~~ Après téléchargement depuis `nodejs.org`, vérifiez l'archive avant de l'extraire : ~~~bash printf '%s %s\n' \ '9749e988f437343b7fa832c69ded82a312e41a03116d766797ac14f6f9eee578' \ 'node-v22.23.1-linux-x64.tar.xz' | sha256sum --check sudo tar -xJf node-v22.23.1-linux-x64.tar.xz -C /opt /opt/node-v22.23.1-linux-x64/bin/node --version /opt/node-v22.23.1-linux-x64/bin/npm --version ~~~ Un répertoire versionné sous `/opt` présente deux avantages : le chemin utilisé par systemd ne change pas sans action explicite et le retour arrière ne dépend pas d'une réinstallation réseau. Évitez de faire pointer immédiatement un lien symbolique partagé comme `/opt/node-current` vers la nouvelle version. Ce lien recréerait un couplage entre les applications si plusieurs services l'utilisent. ## Valider la compatibilité au niveau du projet Le champ `engines` de `package.json` documente la plage attendue : ~~~json { "engines": { "node": ">=22 <23" } } ~~~ npm peut signaler une incompatibilité sans nécessairement interrompre l'installation. Ce champ est donc un garde-fou documentaire, pas une preuve suffisante. La validation réelle doit utiliser le nouveau binaire : ~~~bash export PATH="/opt/node-v22.23.1-linux-x64/bin:$PATH" node --version npm ci npm run lint npm test npm run build ~~~ Les dépendances contenant du code natif méritent une attention particulière. Elles peuvent devoir être recompilées pour l'ABI du nouveau runtime. C'est une raison de préférer `npm ci` dans une release propre plutôt que de réutiliser un ancien répertoire `node_modules`. Cette discipline rejoint les principes détaillés dans Architecture web durable : livrer vite sans dette : une livraison reproductible réduit le nombre de variables changées en même temps. ### Distinguer compatibilité déclarée et compatibilité démontrée Une plage de versions dans `package.json` exprime l'intention des mainteneurs, mais elle ne couvre pas votre combinaison exacte de dépendances, de configuration et de données. À l'inverse, un avertissement npm ne signifie pas nécessairement que l'application est inutilisable. La décision doit reposer sur les résultats du projet : installation déterministe, analyse statique, tests, compilation puis démarrage réel de l'artefact. Conservez ces résultats avec la version exacte de Node.js, npm et du lockfile. Si une anomalie apparaît après la mise en production, cette trace permet de savoir ce qui a réellement été qualifié. Elle évite aussi qu'un second déploiement reconstruise implicitement avec une autre version mineure et rende le diagnostic confus. Les modules natifs, les outils de génération et les bibliothèques qui lancent des sous-processus sont les candidats prioritaires pour un test ciblé. Vérifiez leurs notes de version lorsque vous franchissez une version majeure de Node.js. Pour une mise à jour mineure au sein d'une même ligne LTS, gardez malgré tout la même chaîne de validation : le coût est faible une fois automatisé et le résultat reste comparable d'une intervention à l'autre. ## Cas Next.js : construire un artefact autonome Avec `output: "standalone"`, Next.js produit `.next/standalone` et un serveur minimal `server.js`. Ce mode limite la quantité de dépendances transférées en production. Il ne copie cependant pas automatiquement `public` ni `.next/static`. Une préparation courante ressemble à ceci : ~~~bash npm run build cp -a public .next/standalone/ mkdir -p .next/standalone/.next cp -a .next/static .next/standalone/.next/ ~~~ Le service doit ensuite lancer le serveur généré avec le runtime ciblé : ~~~ini [Service] User=mon-application WorkingDirectory=/var/www/mon-application/current EnvironmentFile=/etc/mon-application.env ExecStart=/opt/node-v22.23.1-linux-x64/bin/node .next/standalone/server.js Restart=on-failure RestartSec=5 ~~~ Utiliser un chemin absolu évite qu'une modification du `PATH` système affecte le prochain redémarrage. L'unité ne doit contenir ni secret ni jeton. Ceux-ci restent dans un fichier d'environnement lisible uniquement par le compte approprié. ## Basculer un seul service Avant la modification, sauvegardez l'unité et notez la release active. Préparez la nouvelle release dans un autre répertoire, testez-la sur un port temporaire lié à `127.0.0.1`, puis changez uniquement le service concerné. ~~~bash sudo systemd-analyze verify /etc/systemd/system/mon-application.service sudo systemctl daemon-reload sudo systemctl restart mon-application.service sudo systemctl status mon-application.service --no-pager sudo journalctl -u mon-application.service --since '-5 minutes' --no-pager ~~~ Ne redémarrez pas tous les services « par précaution ». Cela élargit inutilement l'incident potentiel et efface la preuve que les autres applications étaient stables pendant l'opération. Pour industrialiser ce type de livraison, DevPush et le déploiement continu présente les contrôles utiles autour d'un pipeline. L'automatisation reste bénéfique lorsqu'elle conserve une cible étroite et un retour arrière explicite. ## Contrôler après la bascule Un processus actif n'est pas encore une application saine. Vérifiez successivement : 1. **Le processus** : PID stable, absence de boucle de redémarrage et bon chemin dans `/proc`. 2. **Le port local** : réponse HTTP sur `127.0.0.1` avec le code attendu. 3. **Le reverse proxy** : réponse via le domaine public, certificat TLS valide et absence de `502`. 4. **Le fonctionnel** : page principale, ressource statique, action métier en lecture et, si possible, test synthétique. 5. **Les voisins** : état systemd et URL de santé des autres applications du VPS. 6. **Les ressources** : mémoire, CPU, espace disque et journaux pendant quelques minutes. Comparez ces mesures à l'état relevé avant l'intervention. Sans référence, une hausse de mémoire ou une latence inhabituelle peut passer inaperçue. ### Observer assez longtemps pour détecter les défauts différés Tous les problèmes ne se manifestent pas au premier appel HTTP. Une tâche planifiée peut charger un module rarement utilisé, un traitement d'image peut solliciter une dépendance native et une connexion longue peut révéler un changement de comportement sous charge. Gardez donc les journaux et les métriques sous surveillance pendant une fenêtre représentative du trafic. Le contrôle doit rester proportionné au service. Pour un site vitrine, quelques parcours synthétiques, le taux d'erreur et la consommation mémoire peuvent suffire. Pour une application métier, ajoutez les files de travaux, les tâches cron, les connexions à la base et les intégrations externes. Surveillez aussi la tendance, pas uniquement une valeur instantanée : une mémoire qui progresse lentement après chaque requête est plus inquiétante qu'un pic bref et expliqué au démarrage. L'article Monitoring applicatif avec Sentry et OpenTelemetry détaille les signaux utiles pour transformer cette période d'observation en validation mesurable. ## Préparer un retour arrière réellement exécutable Le rollback doit être possible sans reconstruire dans l'urgence. Conservez : - l'ancienne release complète - l'ancien runtime sous son chemin versionné - une copie de l'unité systemd précédente - les commandes exactes de restauration Si le nouveau service échoue, restaurez l'ancien `ExecStart` ou le lien `current`, rechargez systemd, redémarrez uniquement l'application et répétez les contrôles. Ne supprimez l'ancien runtime qu'après une période d'observation adaptée au trafic et après avoir confirmé qu'aucun autre service ne le référence. Avant toute suppression, recherchez le chemin du runtime dans les unités systemd, scripts de déploiement, tâches cron et processus actifs. Un répertoire qui semble ancien peut encore être la dépendance silencieuse d'un service peu sollicité. ## La stratégie en une phrase Une mise à jour Node.js sûre sur un VPS partagé ne remplace pas « Node.js sur le serveur ». Elle installe un runtime supplémentaire, qualifie un artefact avec ce runtime, puis migre une application à la fois avec des preuves avant, pendant et après la bascule. ## Sources - Node.js, calendrier et statut des versions - Node.js v22.23.1, sommes de contrôle officielles - Next.js, configuration `output: "standalone"` - npm, champ `engines` de `package.json` - systemd, documentation des unités de service La meilleure mise à jour est celle dont les autres applications ne remarquent jamais le passage.

#linux

Mettre à jour Node.js en production sans casser les autres applications