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.
Main features
- Script daemonization
- 0s downtime reload
- Builtin load-balancer
- Startup scripts for Ubuntu and CentOS
- Stop unstable process (avoid infinite loop)
- Monitoring in console
- HTTP API
- Remote control and real time interface API
Tested with Node v0.11, v0.10, v0.8 (https://travis-ci.org/Unitech/pm2).
Compatible CoffeeScript.
Works on Linux & MacOS.
Doc
- 0.5.x documentation : 0.5.x
Readme Contents
# Installation
npm install -g pm2
# Usage/Features
$ npm install pm2 -g
$ pm2 start app.js -i 4
$ pm2 start app.js --name my-api
$ pm2 list
$ pm2 monit
$ pm2 logs
$ pm2 stop all
$ pm2 restart all
$ pm2 reload all
$ pm2 stop 0
$ pm2 restart 0
$ pm2 startup
$ pm2 web
$ pm2 delete 0
$ pm2 delete all
## Different ways to launch a process
$ pm2 start app.js -i max
$ pm2 start app.js -i 3
$ 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
You can also execute app in other languages (the fork mode):
$ pm2 start my-bash-script.sh -x --interpreter bash
$ pm2 start my-python-script.py -x --interpreter python
## 0s downtime reload
This feature permits to reload code without loosing queries connection.
Warning :
- Only for networked app
- Running on Node 0.11.x
- In cluster mode (default mode)
$ pm2 reload all
Thanks to TruongSinh Tran-Nguyen https://github.com/truongsinh
## CoffeeScript
$ pm2 start my_app.coffee
That's all !
## Fork mode - execute script in different languages
The default mode of PM2 consists of wrapping the code of your node app 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 do, called the fork mode.
In fork mode all options are the same than the cluster mode (restart, delete...).
But, by the way, you can't cluster natively in fork mode as cluster do (can't use the -i option).
Here is how to start your app in 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
## 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
## pm2 list
List infos about all processes managed by pm2. It shows also how many times a process has been restarted because of an unhandled exception.
## pm2 monit
Monitor CPU and memory usage of every node process (and also clustered processes) managed by pm2.
## pm2 automatic startup script generation
PM2 provides an automatic way to keep Node processes alive.
It uses a System V init script compatible Ubuntu and CentOS.
$ pm2 startup
Now you can reboot your server, and already launched processes should be kepts alive.
## pm2 logs
Display logs in streaming of all processes, without having to do a tail -f or something else.
You can also pass [name|id] as parameter to stream only the log of a specified process.
## pm2 health web api endpoint
PM2 can disserve an API endpoint to monitor processes and computer health (cpu usage, memory, network interfaces...)
pm2 web
## Customization
Multiple variables can be customized via the environment :
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,
# Multi process JSON declaration
processes.json :
[{
"name" : "echo",
"script" : "./examples/args.js",
"args" : "['--toto=heya coco', '-d', '1']",
"exec_mode" : "fork_mode"
},{
"name" : "api",
"script" : "./examples/child.js",
"instances" : "4",
"error_file" : "./examples/child-err.log",
"out_file" : "./examples/child-out.log",
"exec_mode" : "cluster_mode",
"port" : 9005
},{
"min_uptime" : "100",
"max_restarts" : "400",
"name" : "auto-kill",
"script" : "./examples/killfast.js"
}]
Then with the cli :
$ pm2 start processes.json
Special options with JSON process declaration
-
"min_uptime":
if a process is restarted with an uptime smaller than this value,
this restart counts as an unstable restart. If this option is not specified,
all restarts are considered unstable.
-
"max_restarts":
if the number of unstable restarts exceeds this number,
the process will be stopped and a message with number with restarts will be logged.
# Contributing/Development mode
Fork PM2 and to hack it it's pretty simple :
$ pm2 kill # kill the current pm2
$ git clone my_pm2_fork.git
$ cd pm2/
$ DEBUG=* PM2_DEBUG=true./bin/pm2 start xxx.js
Everytime you do a modification on the code you have to restart pm2, so just do a ./bin/pm2 kill
before
starting an app or something else.
You have to restart it because the code is daemonized on the memory.
# 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.
# Test
npm test
# They talk about it
MISC
Code structure
Features
- Clusterize your Node networked script without adding one line of code
- Fully tested
- Monitor process/cluster processes health (status, memory, cpu usage, restarted time) via CLI (htop like)
- Monitor server health (processes, cpu core...) via JSON api (pm2 web)
- Launch multiple applications via JSON
- Forever keep alive processes
- Log streaming in realtime (pm2 logs)
- Log uncaught exceptions in error logs
- Track restarted time
- Auto stop processes who exit too fast
- Dump current processes and resurrect (upstart)
Idea bucket
- Remote administration/status checking
- Builtin Inter process communication channel (message bus)
- Auto start of the script at start (upstart)
- V8 GC memory leak detection
- Web interface
- Keeping monitoring data
- Integrated wrk utils endpoint benchmark
- Add homogen communication channel (pubsub/eventemitter2 - wildcard events) (axon pub/sub-message.js)
Thanks to Devo.ps and Wiredcraft for their knowledge and expertise.
# License - Apache License v2
Copyright [2013] [Strzelewicz Alexandre as@unitech.io]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.