1 | <div align="center">
|
2 | <br/>
|
3 | <a href="http://pm2.keymetrics.io" title="PM2 Keymetrics link">
|
4 | <img width=710px src="https://raw.githubusercontent.com/Unitech/pm2/master/pres/pm2-v4.png" alt="pm2 logo">
|
5 | </a>
|
6 | <br/>
|
7 | <br/>
|
8 | <b>P</b>(rocess) <b>M</b>(anager) <b>2</b><br/>
|
9 | <i>Runtime Edition</i>
|
10 | <br/><br/>
|
11 |
|
12 | <a href="https://badge.fury.io/js/pm2">
|
13 | <img src="https://badge.fury.io/js/pm2.svg" alt="npm version" height="18">
|
14 | </a>
|
15 |
|
16 | <a href="https://www.npmjs.com/package/pm2" title="PM2 on NPM">
|
17 | <img alt="NPM Downloads" src="https://img.shields.io/npm/dm/pm2.svg?style=flat-square"/>
|
18 | </a>
|
19 |
|
20 | <a href="https://travis-ci.org/Unitech/pm2" title="PM2 Tests">
|
21 | <img src="https://travis-ci.org/Unitech/pm2.svg?branch=master" alt="Build Status"/>
|
22 | </a>
|
23 |
|
24 |
|
25 | <br/>
|
26 | <br/>
|
27 | <br/>
|
28 | </div>
|
29 |
|
30 | PM2 is a General Purpose Process Manager and a Production Runtime for Node.js apps with a built-in Load Balancer.
|
31 |
|
32 | Key features:
|
33 | - Simple and efficient process management (start/stop/restart/delete/show/monit)
|
34 | - Keep your application ALWAYS ONLINE with auto restarts and init system script generation
|
35 | - Clusterize Node.js Applications without code change to increase performance and reliability
|
36 | - Hot Reload Node.js Applications without extra configuration
|
37 |
|
38 | Starting an application in production mode is as easy as:
|
39 |
|
40 | ```bash
|
41 | $ pm2 start app.js
|
42 | ```
|
43 |
|
44 | PM2 is constantly assailed by [more than 1800 tests](https://travis-ci.org/Unitech/pm2).
|
45 |
|
46 | Official website: [http://pm2.keymetrics.io/](http://pm2.keymetrics.io/)
|
47 |
|
48 | Works on Linux (stable) & macOS (stable) & Windows (stable).
|
49 | All Node.js versions are supported starting Node.js 0.12.
|
50 |
|
51 | [![NPM](https://nodei.co/npm/pm2.png?downloads=true&downloadRank=true)](https://nodei.co/npm/pm2/)
|
52 |
|
53 | ### Installing PM2
|
54 |
|
55 | ```bash
|
56 | $ npm install pm2 -g
|
57 | ```
|
58 |
|
59 | *npm is a builtin CLI when you install Node.js - [Installing Node.js with NVM](https://keymetrics.io/2015/02/03/installing-node-js-and-io-js-with-nvm/)*
|
60 |
|
61 | ### Start an application
|
62 |
|
63 | You can start any application (Node.js, Python, Ruby, binaries in $PATH...) like that:
|
64 |
|
65 | ```bash
|
66 | $ pm2 start app.js
|
67 | ```
|
68 |
|
69 | Your app is now daemonized, monitored and kept alive forever.
|
70 |
|
71 | [More about Process Management](http://pm2.keymetrics.io/docs/usage/process-management/)
|
72 |
|
73 | ### Managing a Process
|
74 |
|
75 | Once applications are started you can manage them easily:
|
76 |
|
77 | ![Process listing](https://github.com/unitech/pm2/raw/master/pres/pm2-list.png)
|
78 |
|
79 | To list all running processes:
|
80 |
|
81 | ```bash
|
82 | $ pm2 list
|
83 | ```
|
84 |
|
85 | Managing processes is straightforward:
|
86 |
|
87 | ```bash
|
88 | $ pm2 stop <app_name|id|'all'|json_conf>
|
89 | $ pm2 restart <app_name|id|'all'|json_conf>
|
90 | $ pm2 delete <app_name|id|'all'|json_conf>
|
91 | ```
|
92 |
|
93 | To have more details on a specific process:
|
94 |
|
95 | ```bash
|
96 | $ pm2 describe <id|app_name>
|
97 | ```
|
98 |
|
99 | To monitor logs, custom metrics, process information:
|
100 |
|
101 | ```bash
|
102 | $ pm2 monit
|
103 | ```
|
104 |
|
105 | [More about Process Management](http://pm2.keymetrics.io/docs/usage/process-management/)
|
106 |
|
107 | ### Cluster Mode: Node.js Load Balancing & Hot Reload
|
108 |
|
109 | The Cluster mode is a special mode when starting a Node.js application, it starts multiple processes and load-balance HTTP/TCP/UDP queries between them. This increase overall performance (by a factor of x10 on 16 cores machines) and reliability (faster socket re-balancing in case of unhandled errors).
|
110 |
|
111 | Starting a Node.js application in cluster mode that will leverage all CPUs available:
|
112 |
|
113 | ```bash
|
114 | $ pm2 start api.js -i <processes>
|
115 | ```
|
116 |
|
117 | `<processes>` can be `'max'`, `-1` (all cpu minus 1) or a specified number of instances to start.
|
118 |
|
119 | **Hot Reload**
|
120 |
|
121 | Hot Reload allows to update an application without any downtime:
|
122 |
|
123 | ```bash
|
124 | $ pm2 reload all
|
125 | ```
|
126 |
|
127 | Seamlessly supported by all major Node.js frameworks and any Node.js applications without any code change:
|
128 |
|
129 | ![Framework supported](https://raw.githubusercontent.com/Unitech/PM2/development/pres/cluster-support.png)
|
130 |
|
131 | [More informations about how PM2 make clustering easy](https://keymetrics.io/2015/03/26/pm2-clustering-made-easy/)
|
132 |
|
133 | ### Container Support
|
134 |
|
135 | With the drop-in replacement command for `node`, called `pm2-runtime`, run your Node.js application in a proper production environment.
|
136 | We also offer an [officialy supported Docker image](https://hub.docker.com/r/keymetrics/pm2/).
|
137 |
|
138 | Using it is seamless:
|
139 |
|
140 | ```
|
141 | FROM keymetrics/pm2:latest-alpine
|
142 | [...]
|
143 | CMD [ "pm2-runtime", "npm", "--", "start" ]
|
144 | ```
|
145 |
|
146 | [Read More about the dedicated integration](http://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/)
|
147 |
|
148 | ### Terminal Based Monitoring
|
149 |
|
150 | ![Monit](https://github.com/Unitech/pm2/raw/master/pres/pm2-monit.png)
|
151 |
|
152 | Monitor all processes launched straight from the command line:
|
153 |
|
154 | ```bash
|
155 | $ pm2 monit
|
156 | ```
|
157 |
|
158 | ### Monitor PM2 and Applications with our SaaS
|
159 |
|
160 | Once you deploy your application in production, you can monitor, debug and profile it externally with our [SaaS Monitoring](https://keymetrics.io).
|
161 |
|
162 | To start monitoring applications from the terminal:
|
163 |
|
164 | ```bash
|
165 | $ pm2 register
|
166 | ```
|
167 |
|
168 | [More about PM2 Monitoring](http://docs.keymetrics.io/)
|
169 |
|
170 | ### Expose Custom Metrics
|
171 |
|
172 | To get more insights on how your application behave, plug custom metrics inside your code and monitor them with the `pm2 monit` command:
|
173 |
|
174 | In your project install [pmx](https://github.com/keymetrics/pmx):
|
175 |
|
176 | ```bash
|
177 | $ npm install pmx --save
|
178 | ```
|
179 |
|
180 | Then plug a custom metric:
|
181 |
|
182 | ```javascript
|
183 | var Probe = require('pmx').probe();
|
184 |
|
185 | var counter = 1;
|
186 |
|
187 | var metric = Probe.metric({
|
188 | name : 'Counter',
|
189 | value : function() {
|
190 | return counter;
|
191 | }
|
192 | });
|
193 |
|
194 | setInterval(function() {
|
195 | counter++;
|
196 | }, 1000);
|
197 | ```
|
198 |
|
199 | Then to see the metric type from in the terminal:
|
200 |
|
201 | ```bash
|
202 | $ pm2 monitor
|
203 | ```
|
204 |
|
205 | Metric, Counter, Histogram and Meters are [available](http://pm2.keymetrics.io/docs/usage/process-metrics/)
|
206 |
|
207 | ### Log facilities
|
208 |
|
209 | ![Monit](https://github.com/unitech/pm2/raw/master/pres/pm2-logs.png)
|
210 |
|
211 | Displaying logs of a specified process or all processes, in real time is easy:
|
212 |
|
213 | ```bash
|
214 | $ pm2 logs ['all'|app_name|app_id] [--json] [--format] [--raw]
|
215 | ```
|
216 |
|
217 | Standard, Raw, JSON and formated output are available.
|
218 |
|
219 | Examples:
|
220 |
|
221 | ```bash
|
222 | $ pm2 logs APP-NAME # Display APP-NAME logs
|
223 | $ pm2 logs --json # JSON output
|
224 | $ pm2 logs --format # Formated output
|
225 |
|
226 | $ pm2 flush # Flush all logs
|
227 | $ pm2 reloadLogs # Reload all logs
|
228 | ```
|
229 |
|
230 | [More about log management](http://pm2.keymetrics.io/docs/usage/log-management/)
|
231 |
|
232 | ### Startup script generation
|
233 |
|
234 | PM2 can generates and configure a startup script to keep PM2 and your processes alive at every server restart.
|
235 |
|
236 | Supports init systems like: **systemd** (Ubuntu 16, CentOS, Arch), **upstart** (Ubuntu 14/12), **launchd** (MacOSx, Darwin), **rc.d** (FreeBSD).
|
237 |
|
238 | ```bash
|
239 | # Auto detect init system + generate and setup PM2 boot at server startup
|
240 | $ pm2 startup
|
241 |
|
242 | # Manually specify the startup system
|
243 | # Can be: systemd, upstart, launchd, rcd
|
244 | $ pm2 startup [platform]
|
245 |
|
246 | # Disable and remove PM2 boot at server startup
|
247 | $ pm2 unstartup
|
248 | ```
|
249 |
|
250 | To save/freeze a process list on reboot:
|
251 |
|
252 | ```bash
|
253 | $ pm2 save
|
254 | ```
|
255 |
|
256 | [More about startup scripts](http://pm2.keymetrics.io/docs/usage/startup/)
|
257 |
|
258 | ### Commands Cheatsheet
|
259 |
|
260 | ```bash
|
261 | # General
|
262 | $ npm install pm2 -g # Install PM2
|
263 | $ pm2 start app.js # Start, Daemonize and auto-restart application (Node)
|
264 | $ pm2 start app.py # Start, Daemonize and auto-restart application (Python)
|
265 | $ pm2 start npm -- start # Start, Daemonize and auto-restart Node application
|
266 |
|
267 | # Cluster Mode (Node.js only)
|
268 | $ pm2 start app.js -i 4 # Start 4 instances of application in cluster mode
|
269 | # it will load balance network queries to each app
|
270 | $ pm2 reload all # Zero Second Downtime Reload
|
271 | $ pm2 scale [app-name] 10 # Scale Cluster app to 10 process
|
272 |
|
273 | # Process Monitoring
|
274 | $ pm2 list # List all processes started with PM2
|
275 | $ pm2 list --sort=<field> # Sort all processes started with PM2
|
276 | $ pm2 monit # Display memory and cpu usage of each app
|
277 | $ pm2 show [app-name] # Show all information about application
|
278 |
|
279 | # Log management
|
280 | $ pm2 logs # Display logs of all apps
|
281 | $ pm2 logs [app-name] # Display logs for a specific app
|
282 | $ pm2 logs --json # Logs in JSON format
|
283 | $ pm2 flush
|
284 | $ pm2 reloadLogs
|
285 |
|
286 | # Process State Management
|
287 | $ pm2 start app.js --name="api" # Start application and name it "api"
|
288 | $ pm2 start app.js -- -a 34 # Start app and pass option "-a 34" as argument
|
289 | $ pm2 start app.js --watch # Restart application on file change
|
290 | $ pm2 start script.sh # Start bash script
|
291 | $ pm2 start app.json # Start all applications declared in app.json
|
292 | $ pm2 reset [app-name] # Reset all counters
|
293 | $ pm2 stop all # Stop all apps
|
294 | $ pm2 stop 0 # Stop process with id 0
|
295 | $ pm2 restart all # Restart all apps
|
296 | $ pm2 gracefulReload all # Gracefully reload all apps in cluster mode
|
297 | $ pm2 delete all # Kill and delete all apps
|
298 | $ pm2 delete 0 # Delete app with id 0
|
299 |
|
300 | # Startup/Boot management
|
301 | $ pm2 startup # Detect init system, generate and configure pm2 boot on startup
|
302 | $ pm2 save # Save current process list
|
303 | $ pm2 resurrect # Restore previously saved processes
|
304 | $ pm2 unstartup # Disable and remove startup system
|
305 |
|
306 | $ pm2 update # Save processes, kill PM2 and restore processes
|
307 | $ pm2 init # Generate a sample js configuration file
|
308 |
|
309 | # Deployment
|
310 | $ pm2 deploy app.json prod setup # Setup "prod" remote server
|
311 | $ pm2 deploy app.json prod # Update "prod" remote server
|
312 | $ pm2 deploy app.json prod revert 2 # Revert "prod" remote server by 2
|
313 |
|
314 | # Module system
|
315 | $ pm2 module:generate [name] # Generate sample module with name [name]
|
316 | $ pm2 install pm2-logrotate # Install module (here a log rotation system)
|
317 | $ pm2 uninstall pm2-logrotate # Uninstall module
|
318 | $ pm2 publish # Increment version, git push and npm publish
|
319 | ```
|
320 |
|
321 | Also check out the [example folder](https://github.com/Unitech/pm2/tree/master/examples) to discover all features.
|
322 |
|
323 | ## Updating PM2
|
324 |
|
325 | ```bash
|
326 | # Install latest PM2 version
|
327 | $ npm install pm2@latest -g
|
328 | # Save process list, exit old PM2 & restore all processes
|
329 | $ pm2 update
|
330 | ```
|
331 |
|
332 | *PM2 updates are seamless*
|
333 |
|
334 | ## Module system
|
335 |
|
336 | PM2 embeds a simple and powerful module system. Installing a module is straightforward:
|
337 |
|
338 | ```bash
|
339 | $ pm2 install <module_name>
|
340 | ```
|
341 |
|
342 | Here are some PM2 compatible modules (standalone Node.js applications managed by PM2):
|
343 |
|
344 | [**pm2-logrotate**](https://github.com/pm2-hive/pm2-logrotate) auto rotate logs of PM2 and applications managed<br/>
|
345 | [**pm2-webshell**](https://github.com/pm2-hive/pm2-webshell) expose a fully capable terminal in browsers<br/>
|
346 | [**pm2-server-monit**](https://github.com/pm2-hive/pm2-server-monit) monitor your server health<br/>
|
347 |
|
348 | [Writing your own module](http://pm2.keymetrics.io/docs/advanced/pm2-module-system/)
|
349 |
|
350 | ## Keymetrics monitoring
|
351 |
|
352 | [![Keymetrics Dashboard](https://keymetrics.io/assets/images/application-demo.png)](https://app.keymetrics.io/#/register)
|
353 |
|
354 | If you manage your NodeJS app with PM2, Keymetrics makes it easy to monitor and manage apps across servers.
|
355 | Feel free to try it:
|
356 |
|
357 | [Discover the monitoring dashboard for PM2](https://app.keymetrics.io/#/register)
|
358 |
|
359 | Thanks in advance and we hope that you like PM2!
|
360 |
|
361 | ## More about PM2
|
362 |
|
363 | - [Application Declaration via JS files](http://pm2.keymetrics.io/docs/usage/application-declaration/)
|
364 | - [Watch & Restart](http://pm2.keymetrics.io/docs/usage/watch-and-restart/)
|
365 | - [PM2 API](http://pm2.keymetrics.io/docs/usage/pm2-api/)
|
366 | - [Deployment workflow](http://pm2.keymetrics.io/docs/usage/deployment/)
|
367 | - [PM2 on Heroku/Azure/App Engine](http://pm2.keymetrics.io/docs/usage/use-pm2-with-cloud-providers/)
|
368 | - [PM2 auto completion](http://pm2.keymetrics.io/docs/usage/auto-completion/)
|
369 | - [Using PM2 in ElasticBeanStalk](http://pm2.keymetrics.io/docs/tutorials/use-pm2-with-aws-elastic-beanstalk/)
|
370 | - [PM2 Tutorial Series](https://futurestud.io/tutorials/pm2-utility-overview-installation)
|
371 |
|
372 | ## CHANGELOG
|
373 |
|
374 | [CHANGELOG](https://github.com/Unitech/PM2/blob/master/CHANGELOG.md)
|
375 |
|
376 | ## Contributors
|
377 |
|
378 | [Contributors](http://pm2.keymetrics.io/hall-of-fame/)
|
379 |
|
380 | ## License
|
381 |
|
382 | PM2 is made available under the terms of the GNU Affero General Public License 3.0 (AGPL 3.0).
|
383 | We can deliver other licenses, for more informations [contact sales](mailto:sales@keymetrics.io).
|
384 |
|
385 | [![GA](https://ga-beacon.appspot.com/UA-51734350-7/pm2/readme?pixel&useReferer)](https://github.com/igrigorik/ga-beacon)
|