## File: README.md PM2 is a production process manager for Node.js/Bun 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. Starting an application in production mode is as easy as: ```bash $ pm2 start app.js ``` PM2 is battle-tested by [a comprehensive test suite](https://github.com/Unitech/pm2/actions/workflows/node.js.yml). Official website: [https://pm2.keymetrics.io/](https://pm2.keymetrics.io/) Works on Linux, macOS, and Windows. Supports Node.js 18+ and Bun 1+. ## Installing PM2 ### With NPM ```bash $ npm install pm2 -g ``` ### With Bun ```bash $ bun install pm2 -g ``` If you only have Bun installed (no Node.js), symlink `node` to `bun` so PM2's `#!/usr/bin/env node` shebang resolves to Bun's node-compatibility runtime: ```bash $ sudo ln -s $(which bun) /usr/local/bin/node ``` ___ You can install Node.js easily with [NVM](https://github.com/nvm-sh/nvm#installing-and-updating) or [FNM](https://github.com/Schniz/fnm) or install Bun with `curl -fsSL https://bun.sh/install | bash` ### Start an application You can start any application (Node.js, Bun, and also Python, Ruby, binaries in $PATH...) like that: ```bash $ pm2 start app.js ``` Your app is now daemonized, monitored and kept alive forever. ### Managing Applications Once applications are started you can manage them easily: To list all running applications: ```bash $ pm2 list ``` Managing apps is straightforward: ```bash $ pm2 stop $ pm2 restart $ pm2 delete ``` To have more details on a specific application: ```bash $ pm2 describe ``` To monitor logs, custom metrics, application information: ```bash $ pm2 monit ``` [More about Process Management](https://pm2.keymetrics.io/docs/usage/process-management/) ### Cluster Mode: Node.js Load Balancing & Zero Downtime Reload Cluster mode starts multiple Node.js processes and load-balances HTTP/TCP/UDP queries between them. This significantly increases throughput on multi-core machines and improves reliability (faster socket re-balancing in case of unhandled errors). Starting a Node.js application in cluster mode that will leverage all CPUs available: ```bash $ pm2 start api.js -i ``` `` can be `'max'`, `-1` (all cpu minus 1) or a specified number of instances to start. **Zero Downtime Reload** Hot Reload allows you to update an application without any downtime: ```bash $ pm2 reload all ``` [More information about how PM2 makes clustering easy](https://pm2.keymetrics.io/docs/usage/cluster-mode/) ### Container Support With the drop-in replacement command for `node`, called `pm2-runtime`, run your Node.js application in a hardened production environment. Using it is seamless: ```dockerfile RUN npm install pm2 -g CMD [ "pm2-runtime", "npm", "--", "start" ] ``` [Read More about the dedicated integration](https://pm2.keymetrics.io/docs/usage/docker-pm2-nodejs/) ### Terminal Based Monitoring Monitor all processes launched straight from the command line: ```bash $ pm2 monit ``` ### Log Management To consult logs just type the command: ```bash $ pm2 logs ``` Standard, Raw, JSON and formatted output are available. Examples: ```bash $ pm2 logs APP-NAME # Display APP-NAME logs $ pm2 logs --json # JSON output $ pm2 logs --format # Formatted output $ pm2 flush # Flush all logs $ pm2 reloadLogs # Reload all logs ``` To enable log rotation install the following module ```bash $ pm2 install pm2-logrotate ``` [More about log management](https://pm2.keymetrics.io/docs/usage/log-management/) ### Startup Scripts Generation PM2 can generate and configure a Startup Script to keep PM2 and your processes alive at every server restart. Init Systems Supported: **systemd**, **upstart**, **systemv**, **openrc**, **launchd**, **rcd**, **rcd-openbsd**, **smf** ```bash # Generate Startup Script $ pm2 startup # Freeze your process list across server restart $ pm2 save # Remove Startup Script $ pm2 unstartup ``` [More about Startup Scripts Generation](https://pm2.keymetrics.io/docs/usage/startup/) ### 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* ## PM2+ Monitoring If you manage your apps with PM2, PM2+ makes it easy to monitor and manage apps across servers. Feel free to try it: [Discover the monitoring dashboard for PM2](https://app.pm2.io/) Thanks in advance and we hope that you like PM2! ## CHANGELOG [CHANGELOG](https://github.com/Unitech/pm2/blob/master/CHANGELOG.md) ## Contributors [Contributors](https://pm2.keymetrics.io/hall-of-fame/) ## License PM2 is made available under the terms of the GNU Affero General Public License 3.0 (AGPL 3.0). For other licenses [contact us](mailto:contact@keymetrics.io). --- ## File: examples/using-pm2-and-transpilers/README.md ## Coffee Script ``` $ pm2 install coffee-script $ pm2 start echo.coffee ``` ## Typescript ``` $ pm2 install typescript $ pm2 start http.ts ``` ## Livescript ``` $ pm2 install livescript $ pm2 start echo.ls ``` --- ## File: examples/test-all-keymetrics-features/README.md Try all features of Keymetrics: ```bash # Make sure you've created keymetrics account $ pm2 register # Start all applications $ pm2 start process.config.js # Open Dashboard $ pm2 open ``` --- ## File: examples/sourcemap-auto-resolve/README.md Here is a source map support demo. Source map are automatically handled by pm2: ```bash $ pm2 start process.config.js ``` Here is the result: ``` PM2 | App [API-minified] with id [1] and pid [10634], exited with code [1] via signal [SIGINT] PM2 | Starting execution sequence in -fork mode- for app name:API-minified id:1 PM2 | App name:API-minified id:1 online 1|API-mini | Error: muhahahaha 1|API-mini | at Object. (/home/unitech/keymetrics/pm2/examples/sourcemap-auto-resolve/API.js:226:7) 1|API-mini | at Module._compile (module.js:641:30) 1|API-mini | at Object.Module._extensions..js (module.js:652:10) 1|API-mini | at Module.load (module.js:560:32) 1|API-mini | at tryModuleLoad (module.js:503:12) 1|API-mini | at Function.Module._load (module.js:495:3) 1|API-mini | at Function._load (/home/unitech/keymetrics/pm2/node_modules/pmx/lib/transaction.js:94:21) 1|API-mini | at Object. (/home/unitech/keymetrics/pm2/lib/ProcessContainerFork.js:80:21) 1|API-mini | at Module._compile (module.js:641:30) 1|API-mini | at Object.Module._extensions..js (module.js:652:10) PM2 | App [API-minified] with id [1] and pid [10660], exited with code [1] via signal [SIGINT] PM2 | Starting execution sequence in -fork mode- for app name:API-minified id:1 ``` You will see that the line has been resolved: ``` 1|API-mini | Error: muhahahaha 1|API-mini | at Object. (/home/unitech/keymetrics/pm2/examples/sourcemap-auto-resolve/API.js:226:7) 1|API-mini | at Module._compile (module.js:641:30) ``` --- ## File: examples/module-test/README.md This is a sample module that have been generate via `pm2 module:generate`: ``` >>> pm2 module:generate [PM2] Spawning PM2 daemon with pm2_home=/home/unitech/.pm2 [PM2] PM2 Successfully daemonized [PM2][Module] Module name: module-test [PM2][Module] Getting sample app Cloning into 'module-test'... npm notice created a lockfile as package-lock.json. You should commit this file. added 4 packages in 0.939s [PM2][Module] Module sample created in folder: /home/unitech/keymetrics/pm2/examples/module-test Start module in development mode: $ cd module-test/ $ pm2 install . Module Log: $ pm2 logs module-test Uninstall module: $ pm2 uninstall module-test Force restart: $ pm2 restart module-test ``` ## Configuration To add configuration to the module: ``` $ pm2 set module-test:var1 value1 ``` You will then be able to access to this value via ```bash pmx.initModule({ }, function(err, conf) { // var1 = value1 console.log(conf.var1); }); ``` --- ## File: examples/ecosystem-file/README.md Here we have 3 applications (apps folder) that we can start with process file. These process file can be of different format, javascript, json or yaml: ``` . ├── apps │   ├── connection_check.sh │   ├── http.js │   └── worker.js ├── process.config.js ├── process.json └── process.yml ``` To start them: ```bash $ pm2 start process.config.js $ pm2 delete all $ pm2 start process.json $ pm2 delete all $ pm2 start process.yml ``` --- ## File: examples/cluster-tcp/README.md To start tcp application in cluster mode: ```bash $ pm2 start ecosystem.config.js # OR $ pm2 start tcp.js -i max ```