What is PM2?

PM2 is a production process manager for Node.js applications. It keeps your app running 24/7 by:

Auto-restarting when your app crashes
Starting on boot when your server restarts
Clustering to use all CPU cores
Log management with rotation
Monitoring CPU and memory usage

Prerequisites

You need:

A VPS with Node.js installed
A Node.js application to manage
SSH access with root or sudo privileges

Step 1: Install PM2

Install PM2 globally with npm:

sudo npm install -g pm2

Verify the installation:

pm2 --version

Step 2: Start your application

Navigate to your application directory and start it with PM2:

cd /home/youruser/myapp
pm2 start app.js --name myapp

The --name flag gives your app a friendly name for managing it later.

For different entry points:

# Start a specific file
pm2 start server.js --name api

# Start with npm script
pm2 start npm --name myapp -- start

# Start with environment variables
pm2 start app.js --name myapp --env production

Step 3: Configure auto-restart on boot

Generate a startup script for your system:

pm2 startup

PM2 will output a command to run. Copy and execute it:

sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u youruser --hp /home/youruser

Save the current process list:

pm2 save

Now your app will automatically start when the server boots.

Step 4: Basic PM2 commands

Here are the commands you’ll use most often:

# List all running applications
pm2 list

# Show detailed info about an app
pm2 show myapp

# Restart an application
pm2 restart myapp

# Stop an application
pm2 stop myapp

# Delete an application from PM2
pm2 delete myapp

# Restart all applications
pm2 restart all

# View logs
pm2 logs myapp

# View logs for all apps
pm2 logs

# Monitor CPU/memory in real-time
pm2 monit

Step 5: Enable cluster mode

Node.js runs on a single thread by default. Cluster mode lets PM2 spawn multiple instances to use all CPU cores:

pm2 start app.js --name myapp -i max

The -i max flag tells PM2 to spawn one instance per CPU core.

You can also specify an exact number:

pm2 start app.js --name myapp -i 4

To scale an already running app:

pm2 scale myapp 4

Step 6: Use an ecosystem file

For complex configurations, create an ecosystem file:

pm2 ecosystem

This creates ecosystem.config.js. Edit it:

module.exports = {
  apps: [{
    name: 'myapp',
    script: 'app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'development',
      PORT: 3000
    },
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    max_memory_restart: '500M',
    log_date_format: 'YYYY-MM-DD HH:mm:ss',
    error_file: './logs/error.log',
    out_file: './logs/output.log',
    merge_logs: true
  }]
}

Start with the ecosystem file:

pm2 start ecosystem.config.js --env production

Key configuration options:

instances - Number of instances (‘max’ for all CPU cores)
exec_mode - ‘cluster’ for multiple instances, ‘fork’ for single
max_memory_restart - Restart if memory exceeds this limit
env_production - Environment variables for production

Step 7: Log management

View logs in real-time:

pm2 logs myapp --lines 100

Flush all logs:

pm2 flush

Set up log rotation to prevent logs from filling your disk:

pm2 install pm2-logrotate

Configure rotation settings:

pm2 set pm2-logrotate:max_size 10M
pm2 set pm2-logrotate:retain 7
pm2 set pm2-logrotate:compress true

Step 8: Zero-downtime reloads

When deploying updates, use reload instead of restart for zero downtime:

pm2 reload myapp

This restarts instances one by one, keeping your app available throughout.

Monitoring your application

Command line monitoring

pm2 monit

This shows a real-time dashboard with CPU, memory, and logs.

Check status

pm2 status

Shows all apps with their status, CPU, memory, and uptime.

Common configurations

Express.js app

module.exports = {
  apps: [{
    name: 'express-api',
    script: 'server.js',
    instances: 'max',
    exec_mode: 'cluster',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
}

Next.js app

module.exports = {
  apps: [{
    name: 'nextjs-app',
    script: 'node_modules/next/dist/bin/next',
    args: 'start',
    instances: 'max',
    exec_mode: 'cluster',
    env_production: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
}

Multiple apps

module.exports = {
  apps: [
    {
      name: 'api',
      script: 'api/server.js',
      instances: 2,
      exec_mode: 'cluster'
    },
    {
      name: 'worker',
      script: 'worker/index.js',
      instances: 1,
      exec_mode: 'fork'
    }
  ]
}

Troubleshooting

App keeps restarting

Check the logs for errors:

pm2 logs myapp --err --lines 50

Common causes:

Missing dependencies (run npm install)
Port already in use
Syntax errors in your code

High memory usage

Set a memory limit to auto-restart:

pm2 start app.js --max-memory-restart 500M

App not starting on boot

Regenerate the startup script:

pm2 unstartup
pm2 startup
pm2 save

Next steps

Set up Nginx as a reverse proxy for SSL and better performance
Configure automatic deployments from GitHub

Explore our VPS plans for reliable Node.js hosting.

How to use PM2 to manage Node.js applications