PM2 Complete Guide 2026 — Node.js Process Manager for Production Servers

npm install -g pm2
 
# Start an application
pm2 start app.js
pm2 start dist/server.js --name "api"
pm2 start "npm run start" --name "nextjs"
 
# Cluster mode — utilize all CPU cores
pm2 start app.js -i max     # instances = CPU count
pm2 start app.js -i 4       # exactly 4 instances
 
# Status and monitoring
pm2 status
pm2 list
pm2 monit                   # Real-time CPU and memory dashboard
 
# Logs
pm2 logs              # Stream all app logs
pm2 logs api          # Stream specific app logs
pm2 logs --lines 200  # Last 200 lines
 
# Lifecycle
pm2 reload api        # Zero-downtime reload (cluster mode)
pm2 restart api       # Hard restart (brief downtime)
pm2 stop api
pm2 delete api

// ecosystem.config.js
module.exports = {
  apps: [
    {
      name: 'api-server',
      script: 'dist/server.js',
 
      // Cluster mode — use all CPU cores
      instances: 'max',
      exec_mode: 'cluster',
 
      // Environment variables per mode
      env: {
        NODE_ENV: 'development',
        PORT: 3000,
      },
      env_production: {
        NODE_ENV: 'production',
        PORT: 3000,
      },
 
      // Restart behavior
      max_restarts: 10,
      restart_delay: 4000,
      exp_backoff_restart_delay: 100,  // Exponential backoff between restarts
 
      // Auto-restart if memory exceeds 1GB
      max_memory_restart: '1G',
 
      // Logging
      log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
      out_file: './logs/out.log',
      error_file: './logs/error.log',
      merge_logs: true,
 
      // Graceful shutdown
      wait_ready: true,          // Wait for app to send 'ready'
      listen_timeout: 10000,     // Wait 10s for app to be ready
      kill_timeout: 5000,        // Allow 5s for graceful shutdown
 
      // Source maps for better error stack traces
      source_map_support: true,
    },
 
    // Background worker
    {
      name: 'email-worker',
      script: 'dist/workers/email.js',
      instances: 2,
      exec_mode: 'cluster',
      cron_restart: '0 4 * * *',  // Daily restart at 4 AM
      max_memory_restart: '512M',
    },
  ],
}

# Start with production environment
pm2 start ecosystem.config.js --env production
 
# Reload all apps in ecosystem
pm2 reload ecosystem.config.js --env production
 
# Save and restore process list across reboots
pm2 save

# Zero-downtime reload (maintains availability in cluster mode)
pm2 reload api
 
# Deploy script with graceful reload
#!/bin/bash
set -euo pipefail
 
cd /app
git pull origin main
npm ci --production
npm run build
pm2 reload ecosystem.config.js --env production --update-env
 
echo "Deploy complete"

// server.ts
import express from 'express'
import { db } from './db'
import { redis } from './redis'
 
const app = express()
 
const server = app.listen(3000, () => {
  console.log('Server listening on port 3000')
 
  // Signal PM2 that the app is ready to receive traffic
  if (process.send) {
    process.send('ready')
  }
})
 
// Graceful shutdown on SIGINT (sent by PM2 during reload)
process.on('SIGINT', async () => {
  console.log('SIGINT received — graceful shutdown starting')
 
  server.close(async () => {
    await db.end()
    await redis.quit()
    console.log('Graceful shutdown complete')
    process.exit(0)
  })
 
  // Force exit after timeout if shutdown hangs
  setTimeout(() => {
    console.error('Graceful shutdown timed out — forcing exit')
    process.exit(1)
  }, 10000)
})

# Generate systemd startup script (run as your app user)
pm2 startup
 
# PM2 outputs a command like:
# sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u ubuntu --hp /home/ubuntu
# Run that command, then:
 
pm2 save   # Save current process list to ~/.pm2/dump.pm2
 
# Verify it starts on boot
sudo systemctl status pm2-ubuntu
sudo systemctl enable pm2-ubuntu

# Install log rotation module
pm2 install pm2-logrotate
 
# Configure rotation
pm2 set pm2-logrotate:max_size 50M     # Rotate when file exceeds 50MB
pm2 set pm2-logrotate:retain 7         # Keep 7 rotated files
pm2 set pm2-logrotate:compress true    # Gzip rotated files
pm2 set pm2-logrotate:rotateInterval '0 0 * * *'  # Daily at midnight
 
# Flush current logs
pm2 flush
 
# View logs with timestamp
pm2 logs api --timestamp

// ecosystem.config.js — deploy section
module.exports = {
  apps: [...],
  deploy: {
    production: {
      user: 'ubuntu',
      host: ['my-server.com'],
      ref: 'origin/main',
      repo: 'git@github.com:myorg/app.git',
      path: '/app',
      'post-deploy': [
        'npm ci --production',
        'npm run build',
        'pm2 reload ecosystem.config.js --env production',
      ].join(' && '),
    },
  },
}

# Initial server setup
pm2 deploy production setup
 
# Deploy on every release
pm2 deploy production

// Do NOT store state in-process with cluster mode
// These break with multiple workers:
const sessions = new Map()       // Only exists in one worker
let cachedConfig = null          // Each worker caches separately
const jobQueue: Job[] = []       // Jobs only visible to one worker
 
// DO use external shared state:
// Sessions:    Redis (connect-redis)
// Cache:       Redis (ioredis)
// Locks:       Redlock
// Job queues:  BullMQ (backed by Redis)
// Pub/sub:     Redis pub/sub or socket.io-redis