Scale Node.js with Cluster and PM2

Advanced15 min

Use the cluster module and PM2 process manager to run multiple Node.js workers across all CPU cores for production scaling.

Prerequisites

-Node.js installed
-npm install -g pm2 (for PM2 usage)

Steps

Create a basic cluster setup

Use the cluster module to fork worker processes that share the same server port.

$ cat <<'EOF' > cluster.js const cluster = require('cluster'); const os = require('os'); if (cluster.isPrimary) { const cpuCount = os.cpus().length; console.log(`Primary ${process.pid} starting ${cpuCount} workers`); for (let i = 0; i < cpuCount; i++) { cluster.fork(); } cluster.on('exit', (worker, code) => { console.log(`Worker ${worker.process.pid} exited (code: ${code})`); console.log('Starting replacement worker...'); cluster.fork(); }); } else { require('./app.js'); console.log(`Worker ${process.pid} started`); } EOF node cluster.js

Workers share the server port via the OS kernel. Incoming connections are distributed across workers automatically.

Use PM2 for production process management

Start your application with PM2 in cluster mode for automatic worker management, logging, and restarts.

$ pm2 start app.js -i max --name my-app

The -i max flag creates one worker per CPU core. Use -i 0 for the same effect.

Create a PM2 ecosystem configuration

Define a persistent PM2 configuration file for consistent deployments across environments.

$ cat <<'EOF' > ecosystem.config.js module.exports = { apps: [{ name: 'my-app', script: 'app.js', instances: 'max', exec_mode: 'cluster', max_memory_restart: '500M', env: { NODE_ENV: 'production', PORT: 3000 }, error_file: './logs/err.log', out_file: './logs/out.log', merge_logs: true }] }; EOF pm2 start ecosystem.config.js

Monitor workers with PM2

View real-time status, resource usage, and logs for all running workers.

$ pm2 monit

Perform zero-downtime reload

Gracefully reload all workers one at a time to deploy new code without dropping connections.

$ pm2 reload my-app

reload restarts workers sequentially (zero-downtime). restart kills all workers at once (has downtime).

Ensure your app handles SIGINT gracefully to close connections and flush data before the worker exits.

Full Script

full-script.sh

#!/bin/bash
set -euo pipefail

# Node.js Cluster Scaling with PM2

APP_FILE="${1:-app.js}"
APP_NAME="${2:-my-app}"

echo "==> Checking prerequisites..."
node --version
pm2 --version 2>/dev/null || { echo "Installing PM2..."; npm install -g pm2; }

echo "==> CPU cores available: $(nproc)"

echo "==> Creating PM2 ecosystem config..."
cat > ecosystem.config.js <<EOF
module.exports = {
  apps: [{
    name: '${APP_NAME}',
    script: '${APP_FILE}',
    instances: 'max',
    exec_mode: 'cluster',
    max_memory_restart: '500M',
    watch: false,
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    merge_logs: true,
    autorestart: true,
    max_restarts: 10,
    restart_delay: 1000
  }]
};
EOF

mkdir -p logs

echo "==> Starting cluster..."
pm2 start ecosystem.config.js

echo ""
echo "==> Cluster status:"
pm2 status

echo ""
echo "Useful commands:"
echo "  pm2 monit         # Real-time monitoring"
echo "  pm2 reload ${APP_NAME}  # Zero-downtime reload"
echo "  pm2 logs           # View logs"
echo "  pm2 stop ${APP_NAME}    # Stop all workers"
echo "  pm2 save           # Save process list for startup"
echo "  pm2 startup        # Generate OS startup script"

FAQ

Discussion

Loading comments...

#!/bin/bash set -euo pipefail # Node.js Cluster Scaling with PM2 APP_FILE="${1:-app.js}" APP_NAME="${2:-my-app}" echo "==> Checking prerequisites..." node --version pm2 --version 2>/dev/null || { echo "Installing PM2..."; npm install -g pm2; } echo "==> CPU cores available: $(nproc)" echo "==> Creating PM2 ecosystem config..." cat > ecosystem.config.js <<EOF module.exports = { apps: [{ name: '${APP_NAME}', script: '${APP_FILE}', instances: 'max', exec_mode: 'cluster', max_memory_restart: '500M', watch: false, env: { NODE_ENV: 'production', PORT: 3000 }, error_file: './logs/err.log', out_file: './logs/out.log', merge_logs: true, autorestart: true, max_restarts: 10, restart_delay: 1000 }] }; EOF mkdir -p logs echo "==> Starting cluster..." pm2 start ecosystem.config.js echo "" echo "==> Cluster status:" pm2 status echo "" echo "Useful commands:" echo " pm2 monit # Real-time monitoring" echo " pm2 reload ${APP_NAME} # Zero-downtime reload" echo " pm2 logs # View logs" echo " pm2 stop ${APP_NAME} # Stop all workers" echo " pm2 save # Save process list for startup" echo " pm2 startup # Generate OS startup script"