Gérer, monitorer et déployer des applications Node.js en production avec PM2 — process manager, clusters, logs, déploiement automatisé et survie aux redémarrages.
Passer des dizaines d'options en ligne de commande à chaque démarrage n'est pas maintenable. Le fichier ecosystem.config.js centralise toute la configuration de vos applications — environnements, variables, options de cluster, comportement en cas de crash.
pm2 ecosystemPM2 crée un ecosystem.config.js dans le répertoire courant avec un template commenté. Voici une version propre pour commencer :
module.exports = {
apps: [
{
name: 'api',
script: './src/index.js',
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: '500M',
env: {
NODE_ENV: 'development',
PORT: 3000,
},
env_production: {
NODE_ENV: 'production',
PORT: 8080,
},
},
],
}Démarrer avec ce fichier :
pm2 start ecosystem.config.js
pm2 start ecosystem.config.js --env productionscriptLe point d'entrée de l'application. Peut être un fichier .js, mais aussi une commande :
// Fichier directement
script: './dist/index.js'
// Package.json script
script: 'npm',
args: 'run start'
// TypeScript avec ts-node
script: 'ts-node',
args: 'src/index.ts'instances et exec_modeinstances: 1, // 1 processus
instances: 4, // 4 processus
instances: 'max', // autant que de cœurs CPU
exec_mode: 'fork', // 1 instance (défaut)
exec_mode: 'cluster', // N instances avec load balancinginstances: 'max' avec exec_mode: 'cluster' est la configuration standard pour maximiser les performances. PM2 distribue les requêtes HTTP entre toutes les instances automatiquement — sans modifier votre code.
autorestartautorestart: true, // relance en cas de crash (défaut: true)
restart_delay: 4000, // attendre 4s avant de relancer
max_restarts: 10, // maximum 10 redémarrages consécutifs
min_uptime: '5s', // considéré "stable" après 5s de vieSi l'app crashe avant min_uptime, PM2 considère le redémarrage comme un échec et décrémente le compteur max_restarts. Quand max_restarts atteint 0, PM2 arrête de relancer et met l'app en errored. Ça évite une boucle infinie de crash-restart qui consomme des ressources.
watch et ignore_watchwatch: false, // production : toujours false
watch: ['src', 'config'], // dev : surveiller ces dossiers
ignore_watch: ['node_modules', 'logs', '*.log'],env: {
NODE_ENV: 'development',
PORT: 3000,
DB_URL: 'postgresql://localhost/mydb_dev',
},
env_staging: {
NODE_ENV: 'staging',
PORT: 3000,
DB_URL: 'postgresql://staging-server/mydb',
},
env_production: {
NODE_ENV: 'production',
PORT: 8080,
DB_URL: 'postgresql://prod-server/mydb',
},Nommez vos environnements env_[nom]. Démarrez avec --env [nom] :
pm2 start ecosystem.config.js --env staging
pm2 start ecosystem.config.js --env productionLes secrets ne vont pas dans ce fichier. DB_URL avec un mot de passe en clair dans un fichier commité sur GitHub est une fuite de credentials. Utilisez un .env chargé dans le code via dotenv, ou des variables d'environnement système.
module.exports = {
apps: [
{
name: 'api',
script: './dist/index.js',
instances: 'max',
exec_mode: 'cluster',
autorestart: true,
watch: false,
max_memory_restart: '512M',
min_uptime: '10s',
max_restarts: 5,
restart_delay: 3000,
// Logs
out_file: './logs/out.log',
error_file: './logs/error.log',
log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
merge_logs: true, // un seul fichier pour toutes les instances
env_production: {
NODE_ENV: 'production',
PORT: 3000,
},
},
// Deuxième app dans le même fichier
{
name: 'worker',
script: './dist/worker.js',
instances: 1,
exec_mode: 'fork',
autorestart: true,
env_production: {
NODE_ENV: 'production',
},
},
],
}merge_logs: true combine les logs de toutes les instances cluster dans un seul fichier — plus lisible que api-0-out.log, api-1-out.log, etc.
# Démarrer toutes les apps du fichier
pm2 start ecosystem.config.js --env production
# N'en démarrer qu'une
pm2 start ecosystem.config.js --only api --env production
# Recharger seulement le worker
pm2 reload ecosystem.config.js --only workerModifier ecosystem.config.js ne recharge pas automatiquement les apps. Deux options :
# Option 1 : reload (sans coupure si cluster)
pm2 reload ecosystem.config.js
# Option 2 : delete + start (propre, avec coupure)
pm2 delete all
pm2 start ecosystem.config.js --env productionEn production avec du trafic, toujours reload.
Le fichier de configuration donne une base solide. Le chapitre suivant exploite le mode cluster pour faire scaler votre app sur plusieurs cœurs CPU.