0
# PM2
1

2
PM2 is a production process manager for Node.js applications with a built-in load balancer. It provides daemon-like process management, built-in load balancing, zero-downtime reloads, cluster mode for horizontal scaling, comprehensive monitoring, automatic crash recovery, and container integration. PM2 is essential for production Node.js application lifecycle management with enterprise-grade reliability and performance optimization capabilities.
3

4
## Package Information
5

6
- **Package Name**: pm2
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install pm2 -g` (global) or `npm install pm2` (local)
10
- **CLI Usage**: Global installation provides `pm2`, `pm2-dev`, `pm2-docker`, `pm2-runtime` commands
11
- **Programmatic Usage**: Require as a Node.js module for API access
12

13
## Core Imports
14

15
For programmatic use:
16

17
```javascript
18
const pm2 = require('pm2');
19
```
20

21
For TypeScript:
22

23
```typescript
24
import * as pm2 from 'pm2';
25
import { StartOptions, ProcessDescription } from 'pm2';
26
```
27

28
Custom PM2 instance:
29

30
```javascript
31
const PM2 = require('pm2').custom;
32
const customPm2 = new PM2({
33
  pm2_home: '/custom/path',
34
  daemon_mode: false
35
});
36
```
37

38
## Basic Usage
39

40
### Programmatic API
41

42
```javascript
43
const pm2 = require('pm2');
44

45
// Connect to PM2 daemon
46
pm2.connect((err) => {
47
  if (err) {
48
    console.error(err);
49
    process.exit(2);
50
  }
51

52
  // Start a process
53
  pm2.start({
54
    script: 'app.js',
55
    name: 'my-app',
56
    instances: 'max',
57
    exec_mode: 'cluster'
58
  }, (err, apps) => {
59
    if (err) {
60
      console.error(err);
61
      return pm2.disconnect();
62
    }
63

64
    // List all processes
65
    pm2.list((err, processes) => {
66
      console.log(processes);
67
      pm2.disconnect();
68
    });
69
  });
70
});
71
```
72

73
### CLI Usage
74

75
```bash
76
# Start an application
77
pm2 start app.js --name "my-app" -i max
78

79
# List all processes
80
pm2 list
81

82
# Monitor processes
83
pm2 monit
84

85
# Stop all processes
86
pm2 stop all
87

88
# Reload with zero downtime
89
pm2 reload all
90

91
# Save current process list
92
pm2 save
93

94
# Resurrect saved processes
95
pm2 resurrect
96
```
97

98
## Architecture
99

100
PM2 is built around several key components:
101

102
- **Daemon (God)**: Background process managing all applications
103
- **Client API**: Programmatic interface for process management operations
104
- **CLI Interface**: Command-line tool providing full functionality access
105
- **Process Containers**: Wrapper components handling different execution modes (fork, cluster)
106
- **Load Balancer**: Built-in HTTP load balancing for cluster mode
107
- **Monitoring System**: Real-time process metrics and log management
108
- **Configuration System**: Persistent settings and ecosystem file support
109
- **Module System**: Plugin architecture for extending functionality
110

111
## Capabilities
112

113
### Process Management
114

115
Core process lifecycle operations including starting, stopping, restarting, and deleting managed processes. Supports multiple execution modes and clustering.
116

117
```javascript { .api }
118
// Connection management
119
function connect(callback: (err: Error) => void): void;
120
function connect(noDaemonMode: boolean, callback: (err: Error) => void): void;
121
function disconnect(): void;
122

123
// Process lifecycle
124
function start(options: StartOptions, callback: (err: Error, proc: Proc) => void): void;
125
function stop(process: string | number, callback: (err: Error, proc: Proc) => void): void;
126
function restart(process: string | number, callback: (err: Error, proc: Proc) => void): void;
127
function reload(process: string | number, callback: (err: Error, proc: Proc) => void): void;
128
function delete(process: string | number, callback: (err: Error, proc: Proc) => void): void;
129
```
130

131
[Process Management](./process-management.md)
132

133
### Monitoring and Information
134

135
Process monitoring, system metrics collection, and detailed process information retrieval. Includes real-time monitoring interfaces and performance profiling.
136

137
```javascript { .api }
138
function list(callback: (err: Error, processes: ProcessDescription[]) => void): void;
139
function describe(process: string | number, callback: (err: Error, description: ProcessDescription[]) => void): void;
140
function launchSysMonitoring(callback?: (err: Error) => void): void;
141
function profile(type: 'cpu' | 'mem', time?: number, callback?: (err: Error) => void): void;
142
```
143

144
[Monitoring and Information](./monitoring.md)
145

146
### Configuration Management
147

148
PM2 configuration management including getting, setting, and persisting configuration values. Supports both runtime and persistent configuration.
149

150
```javascript { .api }
151
function get(key?: string, callback?: (err: Error) => void): void;
152
function set(key: string, value: any, callback?: (err: Error) => void): void;
153
function multiset(values: string, callback?: (err: Error) => void): void;
154
function unset(key: string, callback?: (err: Error) => void): void;
155
```
156

157
[Configuration Management](./configuration.md)
158

159
### CLI Commands
160

161
Comprehensive command-line interface providing 68 commands for process management, monitoring, configuration, and system integration.
162

163
```bash
164
# Core process management
165
pm2 start <script|config> [options]
166
pm2 stop <id|name|all>
167
pm2 restart <id|name|all>
168
pm2 reload <id|name|all>
169
pm2 delete <id|name|all>
170

171
# Information and monitoring
172
pm2 list
173
pm2 describe <id|name>
174
pm2 monit
175
```
176

177
[CLI Commands](./cli-commands.md)
178

179
### Module Management
180

181
PM2 module system for extending functionality with plugins and add-ons. Install, develop, package, and publish PM2 modules for production enhancements.
182

183
```javascript { .api }
184
function install(module_name: string, options?: InstallOptions, callback?: (err: Error) => void): void;
185
function uninstall(module_name: string, callback?: (err: Error) => void): void;
186
function generateModuleSample(app_name: string, callback?: (err: Error) => void): void;
187
function package(module_path: string, callback?: (err: Error) => void): void;
188
function publish(folder: string, options?: PublishOptions, callback?: (err: Error) => void): void;
189
```
190

191
[Module Management](./module-management.md)
192

193
### Version Control Integration
194

195
Git-based deployment and version management for production applications. Automated deployment, rollback, and source code management.
196

197
```javascript { .api }
198
function pullAndRestart(process_name: string, callback?: (err: Error, result: any) => void): void;
199
function pullAndReload(process_name: string, callback?: (err: Error, result: any) => void): void;
200
function pullCommitId(process_name: string, commit_id: string, callback?: (err: Error, result: any) => void): void;
201
function backward(process_name: string, callback?: (err: Error, result: any) => void): void;
202
function forward(process_name: string, callback?: (err: Error, result: any) => void): void;
203
```
204

205
[Version Control Integration](./version-control.md)
206

207
### Docker Integration
208

209
Container-optimized runtime modes, Dockerfile generation, and production-ready containerization with proper signal handling.
210

211
```javascript { .api }
212
function generateDockerfile(script: string, options?: DockerOptions): string;
213
function dockerMode(script: string, options?: DockerOptions, mode?: string): any;
214
```
215

216
```bash { .api }
217
pm2-runtime <script|config> [options]
218
pm2-docker <script|config> [options]
219
```
220

221
[Docker Integration](./docker-integration.md)
222

223
## Core Types
224

225
```typescript { .api }
226
interface StartOptions {
227
  name?: string;
228
  script?: string;
229
  args?: string | string[];
230
  cwd?: string;
231
  env?: { [key: string]: string };
232
  instances?: number;
233
  exec_mode?: string;
234
  watch?: boolean | string[];
235
  merge_logs?: boolean;
236
  output?: string;
237
  error?: string;
238
  log_date_format?: string;
239
  autorestart?: boolean;
240
  max_restarts?: number;
241
  max_memory_restart?: number | string;
242
  kill_timeout?: number;
243
  restart_delay?: number;
244
  wait_ready?: boolean;
245
  namespace?: string;
246
}
247

248
interface ProcessDescription {
249
  name?: string;
250
  pid?: number;
251
  pm_id?: number;
252
  monit?: {
253
    memory?: number;
254
    cpu?: number;
255
  };
256
  pm2_env?: {
257
    pm_cwd?: string;
258
    pm_out_log_path?: string;
259
    pm_err_log_path?: string;
260
    status?: ProcessStatus;
261
    instances?: number | 'max';
262
    pm_uptime?: number;
263
    restart_time?: number;
264
    unstable_restarts?: number;
265
  };
266
}
267

268
type ProcessStatus = 'online' | 'stopping' | 'stopped' | 'launching' | 'errored' | 'one-launch-status' | 'waiting_restart';
269
```
270

271
[Complete TypeScript Definitions](./typescript-definitions.md)