Scaling Node.js with PM2 Cluster Mode for Multi-Core Utilization

Desired Outcome

Run a Node.js network server across all available CPU cores without modifying the application code, using PM2’s built-in cluster mode and load balancer.

Prerequisites

• Node.js LTS installed.
• PM2 installed globally: npm install pm2 -g.
• A Node.js application that creates a TCP/HTTP server (e.g., using http, https, Express, Fastify).
• The application must be stateless; session data should reside in an external store such as Redis.

Procedure

1. Create an Ecosystem Configuration

In the project root, create ecosystem.config.js with the following content:

// ecosystem.config.js
module.exports = {
  apps: [{
    name: 'api-service',
    script: './app.js',
    instances: 'max', // spawn a worker for each CPU core
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development',
    },
    env_production: {
      NODE_ENV: 'production',
    }
  }]
};

2. Start the Cluster

From the project directory, run:

pm2 start ecosystem.config.js --env production

This command requires the user to have permission to bind to the application’s port (standard user for ports >1024; sudo may be needed for privileged ports).

3. Verify the Cluster Is Running

1. Execute pm2 list. The mode column should show cluster and you should see multiple process IDs under the same app name.
2. Run pm2 monit to view a live dashboard. Confirm that CPU usage is spread across different PIDs rather than concentrated on a single core.
3. To test zero-downtime reloads, run pm2 reload all and immediately check the logs with pm2 logs. You should observe workers restarting one after another, not all at once.

Production Updates

Command	Behavior	Production Impact
pm2 restart all	Stops all workers simultaneously then starts them.	Brief downtime while the first worker boots.
pm2 reload all	Stops and starts workers sequentially.	Zero-downtime; traffic continues to be served by workers that are still running.

Limitations and Risks

• Network servers only: Cluster mode functions only for applications that listen on a socket (HTTP, TCP, etc.). Pure scripts or cron jobs will not benefit.
• Memory overhead: Each worker is a full Node.js process. Estimate RAM as per-worker memory × number of cores. Ensure the host has sufficient memory for instances: 'max'.
• Stateless requirement: In-memory session stores are not shared; use Redis, Memcached, or a database.
• Zombie processes: If a worker crashes repeatedly, orphaned processes may linger. Reset the PM2 daemon with pm2 kill before restarting.

Rollback Procedure

If cluster mode causes instability, revert to a single-instance (fork) mode:

1. Stop the cluster: pm2 delete api-service
2. Optional: clear the PM2 daemon: pm2 kill
3. Start a single process: pm2 start app.js --name api-service

This sequence only changes state when the cluster is stopped; the rollback returns the application to a known-good single-process configuration.