PM2 ecosystem.config.js

ecosystem.config.js는 PM2가 하나 이상의 application을 같은 방식으로 start, restart, reload하고 환경별 설정을 적용하도록 만드는 JavaScript configuration file이다.

일반적으로 project root에 ecosystem.config.js를 두고 version control로 관리한다. 다른 위치에 둘 때는 상대 script 경로의 기준이 모호해지지 않도록 cwd를 명시한다.

/srv/my-api/
├── ecosystem.config.js
├── package.json
└── dist/
    └── server.js

PM2 공식 문서는 직접 만드는 JavaScript 설정 파일 이름이 .config.js로 끝나야 인식된다고 안내한다.

pm2 init simple
node --check ecosystem.config.js

pm2 init simple은 최소 예제를 생성한다. 생성된 값을 그대로 운영에 쓰기보다 application 경로, 계정, instance 수와 restart 정책을 검토한다.

module.exports = {
  apps: [
    {
      name: 'my-api',
      cwd: '/srv/my-api',
      script: './dist/server.js',
      exec_mode: 'cluster',
      instances: 2,
      autorestart: true,
      max_memory_restart: '512M',
      restart_delay: 3000,
      time: true,
      env: {
        NODE_ENV: 'development',
        PORT: '3000'
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: '3000'
      }
    }
  ]
}

module.exports = {
  apps: [{
    name: 'worker',
    script: './worker.js',
    env: {
      NODE_ENV: 'development'
    },
    env_production: {
      NODE_ENV: 'production'
    }
  }]
}

pm2 start ecosystem.config.js --env production
pm2 restart ecosystem.config.js --env production --update-env

–env production은 env_production을 선택한다. configuration file에 database password, API token, private key 같은 secret을 직접 넣어 Git에 commit하지 않는다. 별도 secret manager나 권한이 제한된 runtime environment file을 사용하고, PM2 상태·log·diagnostic 출력에 값이 노출되는지도 확인한다.

module.exports = {
  apps: [
    {
      name: 'api',
      cwd: '/srv/my-service',
      script: './dist/api.js'
    },
    {
      name: 'worker',
      cwd: '/srv/my-service',
      script: './dist/worker.js'
    }
  ]
}

pm2 start ecosystem.config.js
pm2 restart ecosystem.config.js --only api
pm2 reload ecosystem.config.js --only "api,worker"
pm2 stop ecosystem.config.js
pm2 delete ecosystem.config.js

–only는 configuration file 안의 특정 application만 대상으로 삼는다.

module.exports = {
  apps: [{
    name: 'my-api',
    script: './dist/server.js',
    exec_mode: 'cluster',
    instances: 2,
    wait_ready: true,
    listen_timeout: 10000,
    kill_timeout: 5000,
    restart_delay: 3000,
    max_restarts: 10
  }]
}

wait_ready: true를 사용하면 application이 준비 완료 시 process.send('ready')를 보내도록 구현해야 한다. graceful shutdown은 PM2가 보내는 signal을 application이 처리하고, 새 request 수락 중단과 기존 connection 정리를 제한 시간 안에 끝내도록 함께 설계한다.

node --check ecosystem.config.js
pm2 start ecosystem.config.js --only my-api
pm2 show my-api
pm2 logs my-api --lines 100
pm2 save

JavaScript syntax 검사가 성공해도 path, port, permission과 runtime secret까지 검증되지는 않는다. production 반영 전 test 환경에서 working directory, log 쓰기 권한, health check, restart와 graceful reload를 확인한다. pm2 save는 검증이 끝난 process list에 대해서만 실행한다.

• configuration의 env가 기본 environment 집합이다.
• –env NAME을 지정하면 대응하는 env_NAME 집합을 선택한다.
• shell에서 변경한 값을 기존 process에 반영할 때는 –update-env가 필요할 수 있다.
• CLI에서 configuration file과 함께 전달한 option은 예상과 다르게 무시될 수 있으므로 지속할 값은 file에 선언하고 pm2 show APP으로 실제 적용값을 확인한다.

• Script not found가 나오면 cwd와 script 조합을 absolute path 기준으로 다시 확인한다.
• environment가 바뀌지 않으면 사용한 –env 이름, env_NAME key와 –update-env 여부를 확인한다.
• cluster에서 scheduled job이 중복 실행되면 별도 worker process로 분리하거나 distributed lock을 사용한다.
• restart loop이면 min_uptime, max_restarts, restart_delay, application exit code와 log를 함께 확인한다.
• watch가 dependency나 log 변경까지 감지하면 ignore_watch를 지정하거나 production watch를 끈다.

• PM2
• node
• PM2 Ecosystem File
• PM2 Process Management

• codex:: 2026-07-23 ecosystem file 구조, 주요 field, environment, restart 정책과 검증 절차를 추가했다.