Skip to main content

PM2

PM2 is a daemon process manager that keeps your application online and helps you manage it. It is commonly used to run Node.js apps in production.

Install​

npm install pm2@latest -g

Update​

pm2 save
npm install pm2 -g
pm2 update

# After updating the node version, re-register the startup script
pm2 unstartup && pm2 startup && pm2 save

# If you hit:
#   Error [TypeError]: Class extends value undefined is not a constructor or null
npm install -g [email protected]
pm2 delete $ID
pm2 start ecosystem.config.js --env production

General​

pm2 ls                 # Display all processes status

# Display all information about a specific process
pm2 show 'APP_NAME_1'
pm2 describe 0

pm2 monit              # Monitor all processes

pm2 logs
pm2 logs APP_NAME_1
pm2 flush              # Empty all log files

# Supporting information
pm2 report

# For the express generator
pm2 start bin/www

pm2 delete 0           # Remove one process from the pm2 list
pm2 delete all         # Remove all processes from the pm2 list

pm2 stop all           # Stop all processes
pm2 stop 0             # Stop a specific process id
pm2 restart 0          # Restart a specific process id

# Generate a startup script
pm2 startup
pm2 startup -u $USER
# Save the app list to be restored at reboot
pm2 save

pm2 updatePM2          # Update the in-memory pm2
pm2 ping               # Ensure the pm2 daemon has been launched

pm2 resurrect          # Restore after an upgrade

Configuration file​

  • Must end with .config.js.
  • Add it to the git repository.
# Generate a sample ecosystem.config.js
pm2 init simple

vi ecosystem.config.js

# Start all applications
pm2 start ecosystem.config.js
pm2 start ecosystem.config.js -u $USER

# Stop all
pm2 stop ecosystem.config.js

# Restart all
pm2 restart ecosystem.config.js

# Reload all
pm2 reload ecosystem.config.js

# Delete all
pm2 delete ecosystem.config.js

# --only also works for start/restart/stop/delete
pm2 start ecosystem.config.js --only "APP_NAME_1,APP_NAME_2"

Example app entry:

module.exports = {
  apps: [
    {
      name: 'app1',
      script: './node_modules/next/dist/bin/next',
      exec_mode: 'fork',
      watch: ['.'],
      env_production: {
        NODE_ENV: 'production',
        NODE_PORT: '16666',
      },
    },
  ],
};

Deployment system​

  • Deploy root path: /deploy:production:path/source.
  • On Windows, run the commands from Git Bash.
# Provision the remote server, using the tree name in `deploy`
pm2 deploy ecosystem.config.js production setup

# Deploy the application
pm2 deploy ecosystem.config.js production

# If git reports local changes but you still want to push what is on the remote,
# force the deployment
pm2 deploy ecosystem.config.js production --force

pm2 start ecosystem.config.js --only hawkbit-ui

# Roll back to a previous deployment ([n]th last, defaults to 1)
pm2 deploy ecosystem.config.js production revert [n]

# Deploy to [ref] — the "ref" setting, or the latest tag. In the config:
#   deploy: {
#     production: {
#       ref: 'origin/master',
#       ref: 'tags/TAG1',
#       ref: '79a9a955e5957ec2afb3806290617de327a5e851',
pm2 deploy ecosystem.config.js production [ref]

# Execute a command on each server
pm2 deploy production exec "pm2 reload all"

Deployment lifecycle​

"pre-setup"        : "echo 'commands or local script path to run on the host before setup starts'"
"post-setup"       : "echo 'commands or a script path to run on the host after cloning the repo'"
"pre-deploy"       : "pm2 startOrRestart ecosystem.json --env production"
"post-deploy"      : "pm2 startOrRestart ecosystem.json --env production"
"pre-deploy-local" : "echo 'this is a locally executed command'"

Multi-host deployment​

"host" : ["212.83.163.1", "212.83.163.2", "212.83.163.3"]

Startup for a non-root user​

# Replace 'ubuntu' with the appropriate distribution from this list:
# ubuntu | centos | redhat | gentoo | systemd | darwin | amazon
sudo su -c "env PATH=$PATH:$(dirname $(nvm which node)) pm2 startup ubuntu -u $USER --hp $HOME"
pm2 save

pm2-logrotate​

Best practice:

  • Do not use error_file or out_file in the PM2 ecosystem file.
pm2 install pm2-logrotate
pm2 conf pm2-logrotate    # View / edit the config

Troubleshooting​

connect EPERM //./pipe/rpc.sock​

Run as administrator.

Windows console error: spawn sh ENOENT​

Use Git Bash.

No pm2 command​

whereis node
sudo ln -s /home/dev/.nvm/versions/node/v16.13.0/bin/node /usr/bin/node
whereis pm2
sudo ln -s /home/dev/.nvm/versions/node/v16.13.0/bin/pm2 /usr/bin/pm2

Limitations​

  • Cannot display the version of a Spring Boot app.
  • Cannot scan the .env file outside a Node.js project.