What is pm2?
PM2 is a production process manager for Node.js applications with a built-in load balancer. It allows you to keep applications alive forever, to reload them without downtime, and to facilitate common system admin tasks.
What are pm2's main functionalities?
Process Management
Start an application with PM2 and keep it running in the background.
pm2 start app.js
Load Balancing
Enable load balancing by starting multiple instances of the application across all CPUs.
pm2 start app.js -i max
Monitoring
Monitor all processes launched with PM2 using a terminal-based dashboard.
pm2 monit
Logging
Display logs of all processes in real-time, or target specific processes.
pm2 logs
Startup Script
Generate a startup script to resurrect PM2 and all processes on server reboot.
pm2 startup
Update Processes
Reload all processes in the cluster without downtime.
pm2 reload all
Other packages similar to pm2
forever
Forever is a simple CLI tool for ensuring that a given script runs continuously (i.e., forever). It is similar to PM2 but lacks some of its advanced features like application monitoring and load balancing.
nodemon
Nodemon is a utility that monitors for any changes in your source and automatically restarts your server. It is often used in development environments, unlike PM2 which is tailored for production use.
strong-pm
StrongLoop Process Manager (strong-pm) is a production process manager for Node.js applications with features like remote deployment and performance monitoring. It is part of the StrongLoop suite, which is now owned by IBM.
supervisor
Supervisor is a client/server system that allows its users to monitor and control a number of processes on UNIX-like operating systems. It is not specifically designed for Node.js and is more general-purpose.
pm2 is a process manager for Node apps with a builtin load-balancer.
Tech notes
pm2 is perfect when you need to spread your stateless NodeJS code accross all CPUs available on a server, to keep all processes alive forever and to 0s reload them.
Main features
- Builtin load-balancer (using the native cluster module)
- Script daemonization
- 0s downtime reload for Node apps
- Startup scripts for with SystemV/SystemD scripts (Ubuntu, Centos...)
- Pause unstable process (avoid infinite loop)
- Restart on file change with --watch
- Monitoring in console
Tested with Node v0.11, v0.10 (https://travis-ci.org/Unitech/pm2).
Recommanded NodeJS version is v0.11.10
Compatible with CoffeeScript.
Works on Linux & MacOS.
Build Status
Master:
Development:
Monitoring dashboard
We gonna release a very nice product, a dashboard to monitor every part of your NodeJS applications. Here are some links :
Thanks in advance and we hope that you like pm2 !
Table of contents
Quick start
Features
Specific
Knowledge
More
Quick start
## Installation
The prefered Node version to run PM2, is the 0.11.10
The latest stable version can always be installed via NPM :
$ npm install pm2@latest -g
If the above fails :
$ npm install git://github.com/Unitech/pm2
Common problems on installation :
## Usage
Hello world :
$ pm2 start app.js
## Examples
Raw examples :
$ pm2 start app.js --name my-api
$ pm2 start app.js -i max
$ pm2 list
$ pm2 describe 0
$ pm2 monit
$ pm2 logs
$ pm2 flush
$ pm2 reloadLogs
$ pm2 stop all
$ pm2 restart all
$ pm2 reload all
$ pm2 stop 0
$ pm2 restart 0
$ pm2 delete 0
$ pm2 delete all
$ pm2 ping
Different ways to launch a process
$ pm2 start app.js -i max
$ pm2 start app.js -i 3
$ pm2 start app.js --node-args="--debug=7001 --trace-deprecation"
$ pm2 start app.js -x
$ pm2 start app.js -x -- -a 23
$ pm2 start app.js --name serverone
$ pm2 start app.json
$ pm2 start app.js -i max -- -a 23
$ pm2 start app.js -i max -e err.log -o out.log
For other nature scripts :
$ pm2 start echo.php
$ pm2 start echo.py
$ pm2 start echo.sh
$ pm2 start echo.rb
$ pm2 start echo.pl
## Options
Options:
-h, --help output usage information
-V, --version output the version number
-v --verbose verbose level
-s --silent hide all messages
-m --mini-list display a compacted list without formatting
-f --force force actions
-n --name <name> set a <name> for script
-i --instances <number> launch [number] instances (for networked app)(load balanced)
-o --output <path> specify out log file
-e --error <path> specify error log file
-p --pid <pid> specify pid file
-x --execute-command execute a program using fork system
-u --user <username> define user when generating startup script
-c --cron <cron_pattern> restart a running process based on a cron pattern
-w --write write configuration in local folder
--interpreter <interpreter> the interpreter pm2 should use for executing app (bash, python...)
--no-daemon run pm2 daemon in the foreground if it doesn't exist already
--merge-logs merge logs
--watch watch application folder for changes
--node-args <node_args> space delimited arguments to pass to node in cluster mode - e.g. --node-args="--debug=7001 --trace-deprecation"
Features
## Transitional state of apps (important)
PM2 is a process manager, as said, pm2 can start, stop, restart and delete processes.
Start a process :
$ pm2 start app.js --name "my-api"
$ pm2 start web.js --name "web-interface"
Now let's say I need to stop the web-interface :
$ pm2 stop web-interface
As you can see the process hasn't disapeared. It is still there but now in stopped
status.
To restart it just do :
$ pm2 restart web-interface
Now I want to delete the app from the pm2 process list.
To do that :
$ pm2 delete web-interface
## Process listing
To list all process running :
$ pm2 list
$ pm2 [list|ls|l|status]
To get more informations about a specific process :
$ pm2 describe 0
## Monitoring CPU/Memory usage
Monitor all processes launched :
$ pm2 monit
## Logs management
Displaying logs in realtime
Displaying logs of specified process or all process in realtime :
$ pm2 logs
$ pm2 logs big-api
$ pm2 flush
Reloading all logs (SIGUSR2/Logrotate)
To reaload all logs, you can send SIGUSR2
to pm2 process.
You can also reload all logs via command line with :
$ pm2 reloadLogs
## Clustering
Launch max
instances (max
depending on the number of CPUs available) and set the load balancer to balance queries between each process :
$ pm2 start app.js --name "API" -i max
If your app is well designed (state less) you gonna be able to process much more queries.
Important concepts to make a NodeJS app stateless :
## Reloading without downtime
This special feature has been added to PM2 a while ago.
Warning It only works for apps in cluster mode (the default mode), that uses HTTP/HTTPS/Socket connections.
Reloading an app :
$ pm2 reload api
If the reload system hasn't managed to reload gracefully, a timeout will simply kill the process and will restart it.
Graceful reload
Sometimes you can experience a very long reload, or a reload that doesn't work (fallback to restart).
It means that your app still have open connection on exit.
To pass this problem you have to use the graceful reload.
Graceful reload is a mecanism that will send a shutdown message to your process before reloading it.
Example :
process.on('message', function(msg) {
if (msg == 'shutdown') {
console.log('Closing all connections...');
setTimeout(function() {
console.log('Finished closing connections');
process.exit(0);
}, 1500);
}
});
## Startup script
PM2 has the amazing ability to generate startup scripts and configure it.
PM2 is also smart enough to save all your process list and to bring back all your processes on restart.
$ pm2 startup [ubuntu|centos|systemd]
Warning This feature is tricky to make it work generically, so once PM2 has setup your startup script, reboot your server to be sure that PM2 put back your apps !
More informations
Two types of startup script are availables:
- SystemV init script (with the option
ubuntu
or centos
) - SystemD init script (with the
systemd
option)
Those options are using :
- ubuntu will use
updaterc.d
and the script lib/scripts/pm2-init.sh
- centos will use
chkconfig
and the script lib/scripts/pm2-init-centos.sh
- systemd will use
systemctl
and the script lib/scripts/pm2.service
User permission
Ah, there is something else, let's say you want the startup script to be executed under another user.
Just use the -u <username
option !
$ pm2 startup ubuntu -u www
Derivated commands
Dump all processes status and environment managed by pm2 :
$ pm2 dump
It populates the file ~/.pm2/dump.pm2
by default.
To bring back the latest dump :
$ pm2 resurrect
## Watch & Restart
This feature permits to restart automatically your app when a file change in the current folder (recursively) :
$ pm2 start app.js --watch
## JSON app declaration
processes.json :
[{
"name" : "echo",
"script" : "./examples/args.js",
"args" : "['--toto=heya coco', '-d', '1']",
"env": {
"NODE_ENV": "production",
"AWESOME_SERVICE_API_TOKEN": "xxx"
}
}
,{
"name" : "api",
"script" : "./examples/child.js",
"instances" : "4",
"error_file" : "./examples/child-err.log",
"out_file" : "./examples/child-out.log",
"pid_file" : "./examples/child.pid",
"exec_mode" : "cluster_mode",
"port" : 9005
},{
"min_uptime" : "100",
"name" : "auto-kill",
"exec_mode" : "fork_mode",
"script" : "./examples/killfast.js"
}]
Then with the cli :
$ pm2 start processes.json
$ pm2 stop processes.json
$ pm2 delete processes.json
$ pm2 restart processes.json
Specific
Specific features
Launching PM2 without daemonizing itself :
$ pm2 start app.js --no-daemon
Sending a system signal to a process :
$ pm2 sendSignal SIGUSR2 my-app
## Configuration file
You can edit these options by editing the file ~/.pm2/custom_options.sh
These variables can be customized :
DAEMON_BIND_HOST : process.env.PM2_BIND_ADDR || 'localhost',
DAEMON_RPC_PORT : process.env.PM2_RPC_PORT || 6666, // RPC commands
DAEMON_PUB_PORT : process.env.PM2_PUB_PORT || 6667, // Realtime events
DEBUG : process.env.PM2_DEBUG || false,
WEB_INTERFACE : process.env.PM2_API_PORT || 9615,
GRACEFUL_TIMEOUT : parseInt(process.env.PM2_GRACEFUL_TIMEOUT) || 4000,
PM2_NODE_OPTIONS : ''
API health endpoint
$ pm2 web
## Enabling Harmony ES6
Enable by default for all processes
You can enable Harmony ES6 by setting PM2_NODE_OPTIONS='--harmony'
environment variable option when you start pm2 (pm2 should not be already daemonized).
To pass this option by default, you can edit ~/.pm2/custom_options.sh
and add :
export PM2_NODE_OPTIONS='--harmony'
Then :
$ pm2 dump
$ pm2 exit
$ pm2 resurrect
If ES6 has been enabled you should see this message at the beggining of each pm2 commands :
● ES6 mode
Enable for specific processes
$ pm2 start my_app.js --node-args="--harmony"
## CoffeeScript
$ pm2 start my_app.coffee
That's all !
## Log and PID files
By default every logs (error and out), pids files, dump, pm2 logs are located in ~/.pm2/
.pm2/
├── dump.pm2
├── custom_options.sh
├── pm2.log
├── pm2.pid
├── logs
└── pids
## Tutorial
How To Use PM2 to Setup a Node.js Production Environment On An Ubuntu VPS
## Execute any script: What is fork mode ?
The default mode of PM2 consists of wrapping the code of your node application into the Node Cluster module. It's called the cluster mode.
There is also a more classical way to execute your app, like node-forever does, called the fork mode.
In fork mode almost all options are the same as the cluster mode. But there is no reload or gracefulReload command.
By using the fork mode you will lose core features of PM2 like the automatic clusterization of your code over all CPUs available and the 0s reload.
So use it if you only need a forever-like behaviour.
Here is how to start your app within a fork:
$ pm2 start app.js -x
$ pm2 list
You can also exec scripts in other languages:
$ pm2 start my-bash-script.sh -x --interpreter bash
$ pm2 start my-python-script.py -x --interpreter python
## JSON app configuration via pipe from stdout
Pull-requests:
#!/bin/bash
read -d '' my_json <<_EOF_
[{
"name" : "app1",
"script" : "/home/projects/pm2_nodetest/app.js",
"instances" : "4",
"error_file" : "./logz/child-err.log",
"out_file" : "./logz/child-out.log",
"pid_file" : "./logz/child.pid",
"exec_mode" : "cluster_mode",
"port" : 4200
}]
_EOF_
echo $my_json | pm2 start -
## Is my production server ready for PM2 ?
Just try the tests before using PM2 on your production server
$ git clone https://github.com/Unitech/pm2.git
$ cd pm2
$ npm install
$ npm test
If a test is broken please report us issues here
Also make sure you have all dependencies needed. For Ubuntu :
$ sudo apt-get install build-essential
$ wget -qO- https://raw.github.com/creationix/nvm/master/install.sh | sh
$ nvm install v0.11.10
$ nvm use v0.11.10
$ nvm alias default v0.11.10
## Contributing/Development mode
To hack PM2, it's pretty simple :
$ pm2 kill
$ git clone my_pm2_fork.git
$ cd pm2/
$ DEBUG=* PM2_DEBUG=true ./bin/pm2 --no-daemon
Each time you edit the code be sure to kill and restart pm2 to make changes taking effect.
Install pm2 development
$ npm install git://github.com/Unitech/pm2
## Known bugs and workarounds
First, install the lastest pm2 version :
$ npm install -g pm2@latest
$ pm2 start index.js -x # start my app in fork mode
For more informations about this issue: #74
Cannot read property 'getsockname' of undefined
When using the cluster mode (by default) you can't use ports from 0 to 1024. If you really need to exec in this range use the fork mode with the -x
parameter.
By using the fork mode you will lose core features of PM2 like the automatic clusterization of your code over all CPUs available and the 0s reload.
## Test
npm test
## They talk about it
Contributors
195 tknew2
184 Alexandre Strzelewicz
20 Alex Kocharin
8 soyuka
6 sailxjx
5 Bret Copeland
4 AS
4 Ville Walveranta
4 achingbrain
3 Ben Postlethwaite
3 Evan You
2 Frederico Silva
2 Ivan Seidel
2 MATSUU Takuto
2 Oleg
2 Willian
2 Yani Iliev
1 Almog Melamed
1 Brent Burgoyne
1 Daniel Pihlstrom
1 Ed Hubbell
1 Eugene Lucash
1 Gil Pedersen
1 Hao-kang Den
1 John Hurliman
1 Jose V. Trigueros
1 Josh Skidmore
1 Juozas Valenčius
1 Kevin Gao
1 Loïc Mahieu
1 Mark Evans
1 Nathan Peck
1 TruongSinh Tran-Nguyen
1 Wes Mason
1 Zihua Li
1 perfectworks
1 subeeshcbabu
Thanks to Devo.ps and Wiredcraft for their knowledge and expertise.
# License
Files in lib/ are made available under the terms of the GNU Affero General Public License (AGPL).
pm2-interface is made under the terms of the Apache V2 license.