Deploying Node.js Apps with PM2 Process Manager

PM2 is a production-grade process manager for Node.js applications. Learn how to deploy and manage Node.js apps with automatic restarts, monitoring, and load balancing.

Why Use PM2?

PM2 provides:

• Auto-restart: Restart apps on crashes or file changes
• Load balancing: Cluster mode for multi-core CPUs
• Log management: Centralized logging
• Monitoring: Real-time performance metrics
• Startup scripts: Auto-start apps on server reboot
• Zero-downtime reloads: Update without downtime

Prerequisites

• Linux server with Ubuntu/Debian
• Node.js installed (sudo apt install nodejs npm)
• Node.js application to deploy
• Root or sudo access

Step 1: Install PM2

Install PM2 globally:

sudo npm install -g pm2

Verify installation:

pm2 --version

Step 2: Deploy Your First App

Start your Node.js app:

pm2 start app.js

With custom name:

pm2 start app.js --name "my-app"

View running apps:

pm2 list

Step 3: Cluster Mode

Utilize all CPU cores:

pm2 start app.js -i max

Or specify number of instances:

pm2 start app.js -i 4

Step 4: PM2 Configuration File

Create ecosystem.config.js:

module.exports = {
  apps: [{
    name: 'my-app',
    script: './app.js',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    },
    error_file: './logs/err.log',
    out_file: './logs/out.log',
    log_date_format: 'YYYY-MM-DD HH:mm:ss Z',
    max_memory_restart: '1G',
    watch: false,
    ignore_watch: ['node_modules', 'logs'],
  }]
}

Start with config:

pm2 start ecosystem.config.js

Step 5: Manage Applications

List all apps:

pm2 list

Stop app:

pm2 stop my-app

Restart app:

pm2 restart my-app

Reload (zero-downtime):

pm2 reload my-app

Delete app:

pm2 delete my-app

Stop all:

pm2 stop all

Restart all:

pm2 restart all

Step 6: View Logs

All logs:

pm2 logs

Specific app:

pm2 logs my-app

Error logs only:

pm2 logs my-app --err

Clear logs:

pm2 flush

Step 7: Monitoring

Real-time monitoring:

pm2 monit

Detailed app info:

pm2 show my-app

Step 8: Startup Script

Generate startup script:

pm2 startup

PM2 will show a command to run, execute it:

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

Save current PM2 process list:

pm2 save

Now PM2 will auto-start your apps on server reboot.

Step 9: Update Application

Method 1: Manual deployment

cd /path/to/app
git pull
npm install
pm2 reload my-app

Method 2: PM2 ecosystem deploy

Add to ecosystem.config.js:

module.exports = {
  apps: [{ ... }],
  deploy: {
    production: {
      user: 'deploy',
      host: '192.168.1.100',
      ref: 'origin/main',
      repo: 'git@github.com:username/repo.git',
      path: '/var/www/production',
      'post-deploy': 'npm install && pm2 reload ecosystem.config.js --env production'
    }
  }
}

Deploy:

pm2 deploy production setup
pm2 deploy production

Step 10: Environment Variables

Set environment variables:

pm2 start app.js --env production

Or in ecosystem.config.js:

env: {
  NODE_ENV: 'development',
  PORT: 3000
},
env_production: {
  NODE_ENV: 'production',
  PORT: 8000
}

Advanced Features

Max memory restart:

pm2 start app.js --max-memory-restart 1G

Cron restart:

pm2 start app.js --cron-restart="0 0 * * *"

Watch and restart:

pm2 start app.js --watch

Interpreter:

pm2 start app.py --interpreter python3

Nginx Reverse Proxy

Configure Nginx for PM2 app:

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Best Practices

1. Use ecosystem.config.js: Version control your PM2 config
2. Cluster mode: Utilize all CPU cores
3. Set max memory: Prevent memory leaks from crashing server
4. Log rotation: Prevent logs from filling disk
5. Monitor regularly: Check pm2 monit for issues
6. Zero-downtime reloads: Use pm2 reload instead of restart
7. Keep PM2 updated: npm install pm2@latest -g

Troubleshooting

App not starting:

Check logs:

pm2 logs my-app --err

High memory usage:

Set max memory restart:

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

PM2 not starting on boot:

Regenerate startup script:

pm2 unstartup
pm2 startup
pm2 save

Useful Commands Reference

pm2 start app.js              # Start app
pm2 list                      # List apps
pm2 stop [app]                # Stop app
pm2 restart [app]             # Restart app
pm2 reload [app]              # Zero-downtime reload
pm2 delete [app]              # Remove app
pm2 logs [app]                # View logs
pm2 monit                     # Monitor
pm2 show [app]                # App details
pm2 save                      # Save process list
pm2 resurrect                 # Restore saved processes
pm2 update                    # Update PM2

Conclusion

PM2 makes Node.js deployment and management effortless with automatic restarts, clustering, and monitoring. Combined with Gumpbox's process management interface, deploying Node.js apps becomes a joy.

Next Steps

• Deploying Applications with Docker
• Setting Up Nginx as a Reverse Proxy