Comment installer Node.js et PM2 sur Ubuntu : Un guide complet pour la production

Node.js est un runtime JavaScript asynchrone et événementiel construit sur le moteur V8 de Chrome, conçu pour exécuter du code JavaScript côté serveur avec un débit élevé. PM2 est un gestionnaire de processus de niveau production pour les applications Node.js qui fournit la démonisation, la récupération automatique après crash, l’agrégation des journaux, l’équilibrage de charge en mode cluster et la génération de scripts de démarrage — le tout depuis une seule interface CLI.

Ce guide couvre chaque méthode d’installation, option de configuration et modèle opérationnel dont vous avez besoin pour exécuter des applications Node.js de manière fiable sur Ubuntu 20.04, 22.04 ou 24.04 LTS dans un environnement de production.

Prérequis

Avant de continuer, confirmez les points suivants :

• Système d’exploitation : Ubuntu 20.04, 22.04 ou 24.04 LTS (serveur ou bureau)
• Privilèges utilisateur : `sudo` ou accès root
• Accès réseau : HTTPS sortant pour télécharger les paquets et les scripts
• curl installé : Exécutez `sudo apt install curl -y` s’il n’est pas déjà présent

Si vous exécutez ceci sur un serveur cloud, un environnement VPS Hosting est la cible de déploiement la plus courante pour les charges de travail Node.js, et tout ce qui est décrit dans ce guide s’applique directement.

Étape 1 : Mettre à jour les paquets système

Synchronisez toujours votre index de paquets et appliquez les mises à jour en attente avant d’installer de nouveaux logiciels. Les métadonnées de paquets obsolètes sont une source fréquente de conflits de dépendances.

“`bash

sudo apt update

sudo apt upgrade -y

“`

Une fois la mise à niveau terminée, redémarrez si le noyau a été mis à jour :

“`bash

sudo reboot

“`

Étape 2 : Installer Node.js — Choisir la bonne méthode

Il existe trois méthodes d’installation principales pour Node.js sur Ubuntu. Chacune présente des compromis distincts en termes de contrôle de version, d’isolation et de disponibilité à l’échelle du système.

Comparaison des méthodes

Méthode 1 : Installer Node.js via NodeSource (Recommandé pour les serveurs)

NodeSource maintient des dépôts Debian/Ubuntu à jour pour chaque ligne de version active de Node.js. Il s’agit de l’approche privilégiée pour les serveurs de production où une version unique et stable est requise à l’échelle du système.

Ajouter le dépôt NodeSource pour la version LTS actuelle :

“`bash

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash –

“`

Ce script effectue plusieurs actions : il détecte votre version d’Ubuntu, ajoute le dépôt apt NodeSource approprié, importe la clé de signature GPG et exécute `apt-get update`. L’indicateur `-E` préserve vos variables d’environnement lors de l’escalade vers sudo, ce qui est important si vous avez des paramètres de proxy configurés.

Installer Node.js et npm :

“`bash

sudo apt install nodejs -y

“`

Le paquet NodeSource regroupe `node` et `npm` dans un seul paquet `nodejs`. Contrairement au paquet Ubuntu universe, il ne les sépare pas.

Vérifier l’installation :

“`bash

node -v

npm -v

“`

Exemple de sortie attendue :

“`

v20.14.0

10.7.0

“`

Épingler à une version majeure spécifique : Si vous avez besoin de Node.js 18 au lieu du LTS actuel, remplacez `setup_lts.x` par `setup_18.x` dans la commande curl. Les flux disponibles incluent `setup_18.x`, `setup_20.x` et `setup_22.x`.

Méthode 2 : Installer Node.js via NVM (Recommandé pour le développement et les environnements multi-versions)

NVM (Node Version Manager) installe Node.js dans votre répertoire personnel, sans nécessiter de privilèges root ni pour Node.js lui-même ni pour les paquets npm installés globalement. Cela élimine les problèmes de permissions qui surviennent couramment lors de l’exécution de `npm install -g` sur Node.js installé au niveau du système.

Installer NVM :

“`bash

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

“`

Vérifiez le dépôt officiel NVM pour le dernier tag de version avant d’exécuter cette commande — le numéro de version dans l’URL change à chaque nouvelle version.

Recharger votre environnement shell :

“`bash

source ~/.bashrc

“`

Si vous utilisez Zsh, sourcez `~/.zshrc` à la place. L’installateur NVM ajoute son bloc d’initialisation au fichier de configuration shell qu’il détecte.

Installer la dernière version LTS de Node.js :

“`bash

nvm install –lts

“`

Installer une version spécifique en parallèle du LTS :

“`bash

nvm install 18

nvm install 20

“`

Basculer entre les versions installées :

“`bash

nvm use 20

nvm alias default 20

“`

La commande `alias default` définit la version qui s’active dans les nouvelles sessions shell, ce qui est essentiel pour les scripts et les tâches cron qui ne sourcent pas votre profil shell interactif.

Vérifier :

“`bash

node -v

npm -v

“`

Écueil critique de NVM pour la production : Étant donné que NVM est limité à l’utilisateur, les scripts de démarrage et les unités systemd de PM2 n’auront pas accès au binaire Node.js géré par NVM, sauf si vous configurez explicitement le chemin. Consultez l’étape 5 pour savoir comment gérer cela correctement.

Étape 3 : Installer PM2

PM2 est distribué en tant que paquet npm et doit être installé globalement afin que son CLI soit disponible à l’échelle du système.

Installer PM2 :

“`bash

sudo npm install -g pm2

“`

Si vous avez installé Node.js via NVM, omettez `sudo` :

“`bash

npm install -g pm2

“`

Vérifier l’installation :

“`bash

pm2 -v

“`

Installer une version spécifique de PM2 (utile pour épingler l’infrastructure) :

“`bash

sudo npm install -g pm2@5.3.1

“`

PM2 version 5.x est la ligne stable actuelle. Elle a introduit des améliorations significatives au tableau de bord web (pm2 plus), à la rotation des journaux et au système de modules par rapport à la v4.

Étape 4 : Gérer les applications Node.js avec PM2

Démarrer une application

Naviguez vers le répertoire de votre application et démarrez-la :

“`bash

cd /var/www/my-app

pm2 start app.js –name "my-app"

“`

Attribuez toujours un indicateur `–name`. Sans lui, PM2 utilise le nom de fichier comme nom de processus, ce qui devient ambigu lorsque vous avez plusieurs services.

Démarrer avec des options supplémentaires :

“`bash

pm2 start app.js –name "my-app" –watch –max-memory-restart 300M

“`

• `–watch` : Redémarre le processus lorsque les fichiers source changent (utile en staging, non recommandé en production)
• `–max-memory-restart 300M` : Redémarre automatiquement le processus s’il dépasse 300 MB de mémoire RSS — une protection essentielle contre les fuites mémoire

Afficher les processus en cours d’exécution

“`bash

pm2 list

“`

Cela affiche un tableau montrant l’ID de processus, le nom, le mode (fork/cluster), le PID, le statut, l’utilisation CPU, la consommation mémoire et le nombre de redémarrages.

Pour un tableau de bord en temps réel :

“`bash

pm2 monit

“`

Contrôler les processus

“`bash

pm2 restart my-app # Graceful restart

pm2 reload my-app # Zero-downtime reload (cluster mode only)

pm2 stop my-app # Stop without removing from process list

pm2 delete my-app # Stop and remove from process list

“`

La différence entre `restart` et `reload` : `restart` tue le processus et en démarre un nouveau, provoquant une brève interruption de service. `reload` (disponible uniquement en mode cluster) fait tourner les workers un par un, maintenant la disponibilité tout au long du processus. Utilisez toujours `reload` dans les déploiements en cluster de production.

Gestion des journaux

“`bash

pm2 logs # Stream logs from all processes

pm2 logs my-app # Stream logs for a specific process

pm2 logs my-app –lines 200 # Show last 200 lines

pm2 flush # Clear all log files

“`

PM2 stocke les journaux dans `~/.pm2/logs/` par défaut. Pour les serveurs de production, installez le module de rotation des journaux pour éviter l’épuisement du disque :

“`bash

pm2 install pm2-logrotate

pm2 set pm2-logrotate:max_size 50M

pm2 set pm2-logrotate:retain 10

pm2 set pm2-logrotate:compress true

“`

Cela fait tourner les journaux lorsqu’ils atteignent 50 MB, conserve 10 archives compressées et empêche la croissance incontrôlée des journaux — un problème courant sur les serveurs à longue durée de fonctionnement qui est fréquemment négligé jusqu’à ce que l’espace disque soit épuisé.

Étape 5 : Configurer PM2 pour démarrer au démarrage du système

PM2 doit être configuré pour survivre aux redémarrages du serveur. Cela est géré via une unité de service systemd générée par PM2 lui-même.

Générer la commande de démarrage :

“`bash

pm2 startup

“`

PM2 affichera une commande adaptée à votre système init et à l’utilisateur actuel. Elle ressemble à ceci :

“`

[PM2] Init System found: systemd

[PM2] To setup the Startup Script, copy/paste the following command:

sudo env PATH=$PATH:/usr/bin /usr/lib/node_modules/pm2/bin/pm2 startup systemd -u ubuntu –hp /home/ubuntu

“`

Copiez et exécutez cette commande exacte. Ne la modifiez pas — le chemin vers le binaire PM2 et le répertoire personnel doivent correspondre à la configuration de votre système.

Configuration du démarrage spécifique à NVM : Si vous avez installé Node.js via NVM, le chemin dans la commande générée pointera vers votre binaire géré par NVM. C’est correct, mais vous devez vous assurer que la version NVM est définie par défaut avant d’exécuter `pm2 startup` :

“`bash

nvm alias default 20

pm2 startup

“`

Sauvegarder la liste de processus actuelle :

“`bash

pm2 save

“`

Cela écrit la liste des processus dans `~/.pm2/dump.pm2`. Au redémarrage, l’unité systemd lit ce fichier et restaure tous les processus sauvegardés. Si vous ajoutez ou supprimez des applications ultérieurement, exécutez à nouveau `pm2 save` pour mettre à jour le snapshot.

Vérifier que l’unité systemd est active :

“`bash

systemctl status pm2-ubuntu

“`

Remplacez `ubuntu` par votre nom d’utilisateur réel.

Étape 6 : Déploiement en production avec les fichiers d’écosystème PM2

Pour tout ce qui va au-delà d’une application à script unique, utilisez le fichier de configuration d’écosystème de PM2. Il fournit des définitions de processus reproductibles et versionnées, et élimine la nécessité de mémoriser de longs indicateurs CLI.

Générer le fichier d’écosystème

“`bash

pm2 ecosystem

“`

Cela crée `ecosystem.config.js` dans le répertoire courant.

Une configuration d’écosystème prête pour la production

“`javascript

module.exports = {

apps: [

{

name: 'api-server',

script: './src/server.js',

instances: 'max',

exec_mode: 'cluster',

watch: false,

max_memory_restart: '500M',

log_date_format: 'YYYY-MM-DD HH:mm:ss Z',

error_file: '/var/log/pm2/api-server-error.log',

out_file: '/var/log/pm2/api-server-out.log',

merge_logs: true,

env: {

NODE_ENV: 'development',

PORT: 3000

},

env_production: {

NODE_ENV: 'production',

PORT: 8080

}

},

{

name: 'worker',

script: './src/worker.js',

instances: 2,

exec_mode: 'fork',

cron_restart: '0 2 * * *',

env_production: {

NODE_ENV: 'production'

}

}

]

};

“`

Explication des décisions de configuration clés :

• `instances: 'max'` : PM2 génère automatiquement un worker par cœur CPU logique. Sur un serveur à 4 cœurs, cela crée 4 processus Node.js, utilisant pleinement le matériel.
• `exec_mode: 'cluster'` : Utilise le module cluster intégré de Node.js. Toutes les instances partagent le même port via l’équilibrage de charge des sockets du système d’exploitation.
• `exec_mode: 'fork'` : Exécute le processus en tant que processus enfant autonome. Requis pour les applications qui ne sont pas des serveurs HTTP (workers de file d’attente, tâches planifiées, serveurs WebSocket avec sessions persistantes).
• `merge_logs: true` : Combine la sortie stdout de toutes les instances du cluster dans un seul fichier journal, facilitant considérablement l’analyse des journaux.
• `cron_restart` : Planifie des redémarrages automatiques en utilisant la syntaxe cron. Utile pour les workers qui accumulent de l’état ou pour appliquer des changements de configuration nocturnes.

Démarrer avec le fichier d’écosystème

“`bash

pm2 start ecosystem.config.js –env production

pm2 save

“`

Flux de déploiement sans interruption de service

Lors du déploiement d’une nouvelle version de votre application :

“`bash

git pull origin main

npm install –production

pm2 reload ecosystem.config.js –env production

“`

`pm2 reload` envoie un `SIGINT` à chaque worker un par un, attend que le nouveau worker soit prêt, puis termine l’ancien. Votre application doit gérer `SIGINT` de manière appropriée et signaler sa disponibilité en utilisant `process.send('ready')` pour que cela fonctionne correctement.

Gestionnaire d’arrêt gracieux dans votre application :

“`javascript

process.on('SIGINT', () => {

server.close(() => {

console.log('HTTP server closed');

process.exit(0);

});

});

“`

Étape 7 : Surveillance et observabilité PM2

Surveillance intégrée

“`bash

pm2 monit

“`

Affiche des graphiques CPU et mémoire en temps réel pour chaque processus dans le terminal.

Informations sur les processus

“`bash

pm2 show my-app

“`

Affiche des métadonnées détaillées : temps de fonctionnement, nombre de redémarrages, versionnage, chemin de l’interpréteur, variables d’environnement et emplacements des fichiers journaux.

Tableau de bord web PM2 (PM2 Plus)

PM2 propose un tableau de bord de surveillance hébergé sur pm2.io. Connectez votre serveur :

“`bash

pm2 link <secret_key> <public_key>

“`

Cela fournit des métriques historiques, des alertes et la gestion des processus à distance — particulièrement utile lors de la gestion de plusieurs serveurs ou lorsque vous avez besoin de visibilité sans accès SSH.

Étape 8 : Mettre à jour Node.js et PM2

Mettre à jour PM2

“`bash

sudo npm install -g pm2@latest

pm2 update

“`

`pm2 update` est essentiel après la mise à niveau du binaire PM2 — il met à jour le démon PM2 en mémoire sans interrompre les processus en cours d’exécution.

Mettre à jour Node.js via NodeSource

Relancez le script de configuration pour la nouvelle version majeure :

“`bash

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash –

sudo apt install nodejs -y

“`

Après la mise à jour de Node.js, redémarrez PM2 pour vous assurer qu’il utilise le nouveau binaire :

“`bash

pm2 restart all

“`

Mettre à jour Node.js via NVM

“`bash

nvm install 22

nvm alias default 22

nvm use 22

pm2 restart all

“`

Si vous avez changé la version NVM par défaut, régénérez le script de démarrage PM2 pour mettre à jour le chemin du binaire dans l’unité systemd :

“`bash

pm2 unstartup

pm2 startup

pm2 save

“`

Considérations de renforcement de la sécurité

L’exécution d’applications Node.js en production nécessite une attention au-delà de la gestion des processus :

• Exécuter en tant qu’utilisateur non-root : N’exécutez jamais PM2 ou Node.js en tant que root. Créez un utilisateur système dédié (`adduser –system –group nodeapp`) et exécutez PM2 sous ce compte.
• Gestion des variables d’environnement : Ne codez pas en dur les secrets dans `ecosystem.config.js`. Utilisez un fichier `.env` chargé via `dotenv`, ou injectez les secrets via votre pipeline de déploiement. Le fichier d’écosystème est généralement soumis au contrôle de version.
• Proxy inverse : Placez Nginx ou Caddy devant votre application Node.js. Cela gère la terminaison TLS, la diffusion de fichiers statiques, la limitation du débit et la mise en mémoire tampon des requêtes. Associez cela à une solution SSL Certificates pour imposer HTTPS.
• Règles de pare-feu : Bloquez l’accès direct à votre port Node.js (par exemple, 3000, 8080) depuis l’internet public. Seul le proxy inverse doit communiquer avec Node.js.
• Limites de ressources : Définissez `max_memory_restart` dans PM2 et configurez les valeurs `ulimit` au niveau du système pour empêcher un processus incontrôlable de déstabiliser le serveur.

Pour les déploiements de production à fort trafic où l’isolation des ressources est critique, un environnement Dedicated Servers offre un contrôle total du matériel et élimine le problème du voisin bruyant inhérent aux infrastructures partagées.

Choisir le bon environnement d’hébergement pour Node.js

Liste de contrôle des décisions techniques

Utilisez cette liste de contrôle avant de déployer Node.js et PM2 en production :

• [ ] Node.js installé via NodeSource (serveur) ou NVM (développement) — pas le paquet Ubuntu universe
• [ ] PM2 installé globalement avec les permissions correctes pour votre méthode d’installation
• [ ] Application démarrée avec l’indicateur `–name` et un seuil `–max-memory-restart` défini
• [ ] Mode cluster activé pour les serveurs HTTP ; mode fork utilisé pour les workers en arrière-plan
• [ ] `pm2 startup` exécuté et la commande générée lancée avec sudo
• [ ] `pm2 save` exécuté après la configuration de tous les processus
• [ ] Module de rotation des journaux installé et configuré
• [ ] Nginx ou Caddy configuré comme proxy inverse avec TLS
• [ ] L’application gère `SIGINT` de manière appropriée pour les rechargements sans interruption de service
• [ ] Secrets gérés en dehors de `ecosystem.config.js`
• [ ] Unité systemd PM2 vérifiée avec `systemctl status pm2-<username>`
• [ ] Le pare-feu bloque l’accès direct aux ports Node.js depuis l’internet public

FAQ

Quelle est la différence entre le mode fork et le mode cluster de PM2 ?

Le mode fork génère l’application en tant que processus enfant unique — une instance, un cœur CPU utilisé. Le mode cluster utilise le module cluster natif de Node.js pour générer plusieurs processus workers qui partagent tous le même port TCP, permettant une véritable utilisation multi-cœur et des rechargements sans interruption de service. Utilisez le mode cluster pour les serveurs HTTP/HTTPS et le mode fork pour les workers, les tâches cron ou les applications qui maintiennent un état interne incompatible avec le partage multi-processus.

Pourquoi PM2 ne redémarre-t-il pas après un redémarrage du serveur même si j’ai exécuté `pm2 startup` ?

La cause la plus courante est que `pm2 save` n’a pas été exécuté après la configuration des processus, de sorte que le fichier dump est vide ou manquant. La deuxième cause la plus courante est une incompatibilité de chemin NVM : si la version NVM par défaut a été modifiée après la génération du script de démarrage, l’unité systemd pointe vers un binaire inexistant. Résolvez ce problème en exécutant `pm2 unstartup`, en définissant la valeur NVM par défaut correcte, puis en relançant `pm2 startup` et `pm2 save`.

PM2 peut-il gérer des processus non-Node.js ?

Oui. PM2 peut gérer n’importe quel exécutable en spécifiant l’interpréteur. Par exemple : `pm2 start script.py –interpreter python3`. Cela rend PM2 utile comme superviseur de processus polyvalent pour les architectures de microservices en langages mixtes.

Comment exécuter plusieurs applications Node.js sur différents ports derrière un seul serveur ?

Définissez chaque application comme une entrée distincte dans `ecosystem.config.js` avec des variables d’environnement `PORT` distinctes. Configurez Nginx comme proxy inverse avec des blocs `server` séparés ou des directives `location` routant vers chaque port. Toutes les applications partagent le même démon PM2 et sont gérées via une seule vue `pm2 list`.

Dois-je utiliser NVM ou NodeSource pour un VPS de production ?

NodeSource est généralement préférable pour les serveurs de production. Il installe Node.js en tant que paquet système, le rendant disponible pour tous les utilisateurs et services système sans dépendances d’initialisation du shell. Le modèle d’activation par utilisateur et par shell de NVM introduit des modes d’échec subtils dans les unités systemd, les tâches cron et les pipelines CI/CD qui s’exécutent en dehors d’une session shell interactive. Réservez NVM aux machines de développement locales où la gestion simultanée de plusieurs versions de Node.js est une exigence réelle.