diff --git a/README.md b/README.md index a5df597b6..043f4ec31 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,8 @@ Runtime Edition

- - bitHound Score + + npm version @@ -30,10 +30,10 @@ PM2 is a General Purpose Process Manager and a Production Runtime for Node.js apps with a built-in Load Balancer. Key features: -- Simple and efficient process management (start/stop/restart/delete/monitoring) -- Keep your application always ONLINE with auto restart and init system script generation -- Automatically clusterize Node.js applications to increase performance and reliability -- Allowing 0 seconds downtime reload for Node.js application without extra configuration +- Simple and efficient process management (start/stop/restart/delete/show/monit) +- Keep your application ALWAYS ONLINE with auto restarts and init system script generation +- Clusterize Node.js Applications without code change to increase performance and reliability +- Hot Reload Node.js Applications without extra configuration Starting an application in production mode is as easy as: @@ -50,7 +50,7 @@ All Node.js versions are supported starting Node.js 0.12. [![NPM](https://nodei.co/npm/pm2.png?downloads=true&downloadRank=true)](https://nodei.co/npm/pm2/) -## Install PM2 +### Installing PM2 ```bash $ npm install pm2 -g @@ -58,7 +58,9 @@ $ npm install pm2 -g *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/)* -## Start an application +### Start an application + +You can start any application (Node.js, Python, Ruby, binaries in $PATH...) like that: ```bash $ pm2 start app.js @@ -68,174 +70,103 @@ Your app is now daemonized, monitored and kept alive forever. [More about Process Management](http://pm2.keymetrics.io/docs/usage/process-management/) -## Container Support - -Using Containers? With the dropin replacement command for `node`, called `pm2-runtime`, run your Node.js application in a proper production environment. -We also offer an [officialy supported Docker image](https://hub.docker.com/r/keymetrics/pm2/). - -Using it is seamless: - -``` -FROM keymetrics/pm2:latest-alpine -[...] -CMD [ "pm2-runtime", "ecosystem.config.js" ] -``` - -[Read More about the dedicated integration](http://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/) +### Managing a Process -## Monitor PM2 and Applications with our SaaS +Once applications are started you can manage them easily: -Once you deploy your application in production you can monitor, debug and profile it externally with our [SaaS Monitoring](https://keymetrics.io). +![Process listing](https://github.com/unitech/pm2/raw/master/pres/pm2-list.png) -To start monitoring applications from the terminal: +To list all running processes: ```bash -$ pm2 register +$ pm2 list ``` -[More about PM2 Monitoring](http://docs.keymetrics.io/) - -## Updating PM2 +Managing processes is straightforward: ```bash -# Install latest PM2 version -$ npm install pm2@latest -g -# Save process list, exit old PM2 & restore all processes -$ pm2 update +$ pm2 stop +$ pm2 restart +$ pm2 delete ``` -*PM2 updates are seamless* - -## Main features - -### Commands overview +To have more details on a specific process: ```bash -# General -$ npm install pm2 -g # Install PM2 -$ pm2 start app.js # Start, Daemonize and auto-restart application (Node) -$ pm2 start app.py # Start, Daemonize and auto-restart application (Python) -$ pm2 start npm -- start # Start, Daemonize and auto-restart Node application - -# Cluster Mode (Node.js only) -$ pm2 start app.js -i 4 # Start 4 instances of application in cluster mode - # it will load balance network queries to each app -$ pm2 reload all # Zero Second Downtime Reload -$ pm2 scale [app-name] 10 # Scale Cluster app to 10 process - -# Process Monitoring -$ pm2 list # List all processes started with PM2 -$ pm2 list --sort= # Sort all processes started with PM2 -$ pm2 monit # Display memory and cpu usage of each app -$ pm2 show [app-name] # Show all information about application - -# Log management -$ pm2 logs # Display logs of all apps -$ pm2 logs [app-name] # Display logs for a specific app -$ pm2 logs --json # Logs in JSON format -$ pm2 flush -$ pm2 reloadLogs - -# Process State Management -$ pm2 start app.js --name="api" # Start application and name it "api" -$ pm2 start app.js -- -a 34 # Start app and pass option "-a 34" as argument -$ pm2 start app.js --watch # Restart application on file change -$ pm2 start script.sh # Start bash script -$ pm2 start app.json # Start all applications declared in app.json -$ pm2 reset [app-name] # Reset all counters -$ pm2 stop all # Stop all apps -$ pm2 stop 0 # Stop process with id 0 -$ pm2 restart all # Restart all apps -$ pm2 gracefulReload all # Gracefully reload all apps in cluster mode -$ pm2 delete all # Kill and delete all apps -$ pm2 delete 0 # Delete app with id 0 - -# Startup/Boot management -$ pm2 startup # Detect init system, generate and configure pm2 boot on startup -$ pm2 save # Save current process list -$ pm2 resurrect # Restore previously saved processes -$ pm2 unstartup # Disable and remove startup system - -$ pm2 update # Save processes, kill PM2 and restore processes -$ pm2 generate # Generate a sample json configuration file +$ pm2 describe +``` -# Deployment -$ pm2 deploy app.json prod setup # Setup "prod" remote server -$ pm2 deploy app.json prod # Update "prod" remote server -$ pm2 deploy app.json prod revert 2 # Revert "prod" remote server by 2 +To monitor logs, custom metrics, process information: -# Module system -$ pm2 module:generate [name] # Generate sample module with name [name] -$ pm2 install pm2-logrotate # Install module (here a log rotation system) -$ pm2 uninstall pm2-logrotate # Uninstall module -$ pm2 publish # Increment version, git push and npm publish +```bash +$ pm2 monit ``` -Also check out the [example folder](https://github.com/Unitech/pm2/tree/master/examples) to discover all features. - -### Process management +[More about Process Management](http://pm2.keymetrics.io/docs/usage/process-management/) -Once applications are started you can list and manage them easily: +### Cluster Mode: Node.js Load Balancing & Hot Reload -![Process listing](https://github.com/unitech/pm2/raw/master/pres/pm2-list.png) +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). -Listing all running processes: +Starting a Node.js application in cluster mode that will leverage all CPUs available: ```bash -$ pm2 list +$ pm2 start api.js -i ``` -Managing processes is straightforward: +`` can be `'max'`, `-1` (all cpu minus 1) or a specified number of instances to start. -```bash -$ pm2 stop -$ pm2 restart -$ pm2 delete -``` +**Hot Reload** -To have more details on a specific process: +Hot Reload allows to update an application without any downtime: ```bash -$ pm2 describe +$ pm2 reload all ``` -[More about Process Management](http://pm2.keymetrics.io/docs/usage/process-management/) - -### Load Balancing & Zero second Downtime Reload - -When an application is started with the `-i ` parameter, the **Cluster Mode** is activated. - -The Cluster Mode starts `` instances of your app and automatically load balance HTTP/TCP/UDP between each instances. This allows to increase overall performance and reliability depending on the number of CPUs available. - Seamlessly supported by all major Node.js frameworks and any Node.js applications without any code change: ![Framework supported](https://raw.githubusercontent.com/Unitech/PM2/development/pres/cluster-support.png) -Main commands: +[More informations about how PM2 make clustering easy](https://keymetrics.io/2015/03/26/pm2-clustering-made-easy/) -```bash -# Enable load-balancer and start 'max' instances (Depending on CPU number) -$ pm2 start app.js -i max +### Container Support -# Update your application with Zero Downtime Reload (requests are not lost) -$ pm2 reload all +With the drop-in replacement command for `node`, called `pm2-runtime`, run your Node.js application in a proper production environment. +We also offer an [officialy supported Docker image](https://hub.docker.com/r/keymetrics/pm2/). + +Using it is seamless: -# Increase / Decrease process number -$ pm2 scale +``` +FROM keymetrics/pm2:latest-alpine +[...] +CMD [ "pm2-runtime", "npm", "--", "start" ] ``` -[More informations about how PM2 make clustering easy](https://keymetrics.io/2015/03/26/pm2-clustering-made-easy/) +[Read More about the dedicated integration](http://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/) ### Terminal Based Monitoring ![Monit](https://github.com/Unitech/pm2/raw/master/pres/pm2-monit.png) -Monitoring all processes launched: +Monitor all processes launched straight from the command line: ```bash $ pm2 monit ``` +### Monitor PM2 and Applications with our SaaS + +Once you deploy your application in production, you can monitor, debug and profile it externally with our [SaaS Monitoring](https://keymetrics.io). + +To start monitoring applications from the terminal: + +```bash +$ pm2 register +``` + +[More about PM2 Monitoring](http://docs.keymetrics.io/) + ### Expose Custom Metrics To get more insights on how your application behave, plug custom metrics inside your code and monitor them with the `pm2 monit` command: @@ -265,7 +196,13 @@ setInterval(function() { }, 1000); ``` -Metric, Counter, Histogram and Meters are available *[documentation](http://pm2.keymetrics.io/docs/usage/process-metrics/)* +Then to see the metric type from in the terminal: + +```bash +$ pm2 monitor +``` + +Metric, Counter, Histogram and Meters are [available](http://pm2.keymetrics.io/docs/usage/process-metrics/) ### Log facilities @@ -318,6 +255,82 @@ $ pm2 save [More about startup scripts](http://pm2.keymetrics.io/docs/usage/startup/) +### Commands Cheatsheet + +```bash +# General +$ npm install pm2 -g # Install PM2 +$ pm2 start app.js # Start, Daemonize and auto-restart application (Node) +$ pm2 start app.py # Start, Daemonize and auto-restart application (Python) +$ pm2 start npm -- start # Start, Daemonize and auto-restart Node application + +# Cluster Mode (Node.js only) +$ pm2 start app.js -i 4 # Start 4 instances of application in cluster mode + # it will load balance network queries to each app +$ pm2 reload all # Zero Second Downtime Reload +$ pm2 scale [app-name] 10 # Scale Cluster app to 10 process + +# Process Monitoring +$ pm2 list # List all processes started with PM2 +$ pm2 list --sort= # Sort all processes started with PM2 +$ pm2 monit # Display memory and cpu usage of each app +$ pm2 show [app-name] # Show all information about application + +# Log management +$ pm2 logs # Display logs of all apps +$ pm2 logs [app-name] # Display logs for a specific app +$ pm2 logs --json # Logs in JSON format +$ pm2 flush +$ pm2 reloadLogs + +# Process State Management +$ pm2 start app.js --name="api" # Start application and name it "api" +$ pm2 start app.js -- -a 34 # Start app and pass option "-a 34" as argument +$ pm2 start app.js --watch # Restart application on file change +$ pm2 start script.sh # Start bash script +$ pm2 start app.json # Start all applications declared in app.json +$ pm2 reset [app-name] # Reset all counters +$ pm2 stop all # Stop all apps +$ pm2 stop 0 # Stop process with id 0 +$ pm2 restart all # Restart all apps +$ pm2 gracefulReload all # Gracefully reload all apps in cluster mode +$ pm2 delete all # Kill and delete all apps +$ pm2 delete 0 # Delete app with id 0 + +# Startup/Boot management +$ pm2 startup # Detect init system, generate and configure pm2 boot on startup +$ pm2 save # Save current process list +$ pm2 resurrect # Restore previously saved processes +$ pm2 unstartup # Disable and remove startup system + +$ pm2 update # Save processes, kill PM2 and restore processes +$ pm2 generate # Generate a sample json configuration file + +# Deployment +$ pm2 deploy app.json prod setup # Setup "prod" remote server +$ pm2 deploy app.json prod # Update "prod" remote server +$ pm2 deploy app.json prod revert 2 # Revert "prod" remote server by 2 + +# Module system +$ pm2 module:generate [name] # Generate sample module with name [name] +$ pm2 install pm2-logrotate # Install module (here a log rotation system) +$ pm2 uninstall pm2-logrotate # Uninstall module +$ pm2 publish # Increment version, git push and npm publish +``` + +Also check out the [example folder](https://github.com/Unitech/pm2/tree/master/examples) to discover all features. + +## Updating PM2 + +```bash +# Install latest PM2 version +$ npm install pm2@latest -g +# Save process list, exit old PM2 & restore all processes +$ pm2 update +``` + +*PM2 updates are seamless* + ## Module system PM2 embeds a simple and powerful module system. Installing a module is straightforward: