PM2 : fichier ecosystem

Le fichier ecosystem décrit les applications une fois pour toutes : il remplace de longues lignes de commande et se versionne avec le projet.

Créer un modèle

pm2 init simple              # génère ecosystem.config.js

Pour un projet dont package.json contient "type": "module", nommer le fichier ecosystem.config.cjs : PM2 le charge comme module CommonJS.

Exemple

ecosystem.config.cjs :

module.exports = {
  apps: [
    {
      name: 'api',
      script: './src/serveur.js',
      cwd: '/srv/monapp',
      instances: 1,
      exec_mode: 'fork',
      max_memory_restart: '300M',
      autorestart: true,
      min_uptime: '10s',
      max_restarts: 10,
      restart_delay: 3000,
      kill_timeout: 5000,
      env: {
        NODE_ENV: 'development',
        PORT: 3000,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
      out_file: '/var/log/monapp/api-out.log',
      error_file: '/var/log/monapp/api-error.log',
      merge_logs: true,
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    },
  ],
};

pm2 start ecosystem.config.cjs --env production
pm2 reload ecosystem.config.cjs --env production --update-env
pm2 delete ecosystem.config.cjs

Options principales

Option	Rôle
`name`	Nom de l’application
`script`	Point d’entrée (ou `npm` avec `args: 'start'`)
`args`	Arguments passés au script
`cwd`	Dossier de travail
`interpreter`	Interpréteur (`node` par défaut ; `python3`, `bash`…)
`instances`	Nombre de processus (`max` : un par cœur)
`exec_mode`	`fork` (défaut) ou `cluster` (voir Mode cluster et reload)
`env`, `env_<nom>`	Variables d’environnement ; `--env <nom>` choisit le jeu `env_<nom>`
`max_memory_restart`	Redémarrage au-delà d’une taille de mémoire
`autorestart`	Redémarrer après un arrêt (`true` par défaut)
`min_uptime`, `max_restarts`	Détection des plantages en boucle
`restart_delay`	Attente entre deux redémarrages (ms)
`kill_timeout`	Délai avant arrêt forcé (ms)
`out_file`, `error_file`	Fichiers de journaux
`merge_logs`	Un seul fichier de journal pour toutes les instances
`watch`	Redémarrer à chaque changement de fichier (développement)
`cron_restart`	Redémarrage planifié (expression cron)

Lancer un script npm

module.exports = {
  apps: [
    {
      name: 'site',
      script: 'npm',
      args: 'start',
      cwd: '/srv/monsite',
    },
  ],
};

Pour de meilleures performances et un arrêt propre, lancer directement le fichier JavaScript plutôt que npm start.

Plusieurs applications

module.exports = {
  apps: [
    { name: 'api', script: './api/serveur.js', env: { PORT: 3000 } },
    {
      name: 'worker',
      script: './worker/index.js',
      instances: 2,
      exec_mode: 'cluster',
    },
    {
      name: 'planificateur',
      script: './tache.js',
      cron_restart: '0 3 * * *',
      autorestart: false,
    },
  ],
};

pm2 start ecosystem.config.cjs --only api lance une seule application du fichier.

Secrets

module.exports = {
  apps: [
    {
      name: 'api',
      script: './src/serveur.js',
      node_args: '--env-file=/etc/monapp.env',
    },
  ],
};

sudo chown root:monapp /etc/monapp.env     # lisible par l'utilisateur de l'application
sudo chmod 640 /etc/monapp.env

Dépannage

Symptôme	Piste
`module is not defined` / `ERR_REQUIRE_ESM`	Projet en ESM : nommer le fichier `.cjs`
`--env production` sans effet	Le jeu doit s’appeler `env_production`
Variables non mises à jour	`pm2 reload … --update-env`
`Script not found`	`cwd` ou `script` incorrect
L’application démarre en double	Ancien processus du même nom : `pm2 delete <nom>` d’abord
Journaux introuvables	`out_file` : dossier inexistant ou sans droits d’écriture

Ubuntu 24.04 et 26.04 : différences à connaître

Le format du fichier ne dépend pas de la distribution. node --env-file demande Node.js 20.6 ou plus.

Pour aller plus loin

Fichier ecosystem
Suite : Mode cluster et reload