ezpm2gui 1.8.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (33) hide show
  1. package/README.md +363 -330
  2. package/bin/ezpm2gui.js +8 -8
  3. package/bin/ezpm2gui.ts +51 -51
  4. package/bin/generate-ecosystem.js +35 -35
  5. package/bin/generate-ecosystem.ts +56 -56
  6. package/dist/server/config/project-configs.json +235 -235
  7. package/dist/server/index.js +4 -4
  8. package/dist/server/routes/deployApplication.js +4 -4
  9. package/dist/server/routes/logStreaming.js +35 -4
  10. package/dist/server/routes/remoteConnections.js +44 -12
  11. package/dist/server/utils/encryption.d.ts +22 -0
  12. package/dist/server/utils/encryption.js +53 -0
  13. package/dist/server/utils/remote-connection.js +3 -3
  14. package/dist/server/utils/remote-metrics-db.js +59 -59
  15. package/package.json +86 -86
  16. package/scripts/postinstall.js +36 -36
  17. package/src/client/build/asset-manifest.json +6 -6
  18. package/src/client/build/favicon.ico +2 -2
  19. package/src/client/build/index.html +1 -1
  20. package/src/client/build/logo192.svg +7 -7
  21. package/src/client/build/logo512.svg +7 -7
  22. package/src/client/build/manifest.json +24 -24
  23. package/src/client/build/static/css/main.8f39974b.css +5 -0
  24. package/src/client/build/static/css/main.8f39974b.css.map +1 -0
  25. package/src/client/build/static/js/main.71236659.js +3 -0
  26. package/src/client/build/static/js/main.71236659.js.map +1 -0
  27. package/dist/server/config/cron-jobs.json +0 -1
  28. package/dist/server/config/remote-connections.json +0 -3
  29. package/src/client/build/static/css/main.9decb204.css +0 -5
  30. package/src/client/build/static/css/main.9decb204.css.map +0 -1
  31. package/src/client/build/static/js/main.28a4a583.js +0 -3
  32. package/src/client/build/static/js/main.28a4a583.js.map +0 -1
  33. /package/src/client/build/static/js/{main.28a4a583.js.LICENSE.txt → main.71236659.js.LICENSE.txt} +0 -0
package/README.md CHANGED
@@ -1,330 +1,363 @@
1
- # EZ PM2 GUI
2
-
3
- A modern web-based graphical user interface for the PM2 process manager, built with TypeScript, Tailwind CSS, and React.
4
-
5
- ## Screenshots
6
-
7
- **Process Dashboard** — live system metrics and every PM2 process at a glance:
8
-
9
- ![Process Dashboard](ezpm2gui/screenshots/01-processes.png)
10
-
11
- **Monitoring** — real-time CPU, memory and uptime per process:
12
-
13
- ![Process Monitor](ezpm2gui/screenshots/02-monitoring.png)
14
-
15
- **Metrics (Live)** — rolling 1-hour sparklines per process, updated every 3 seconds:
16
-
17
- ![Metrics Live](ezpm2gui/screenshots/12-metrics-live.png)
18
-
19
- **Metrics (History)** — SQLite-backed CPU and memory charts with selectable time range:
20
-
21
- ![Metrics History](ezpm2gui/screenshots/13-metrics-history.png)
22
-
23
- **Deploy App** — start new PM2 processes from a structured form:
24
-
25
- ![Deploy App](ezpm2gui/screenshots/04-deploy-app.png)
26
-
27
- **Cron Jobs** — schedule recurring tasks without touching crontab:
28
-
29
- ![Cron Jobs](ezpm2gui/screenshots/08-cron-jobs.png)
30
-
31
- **Settings** — auto-saved preferences for refresh, logs, theme and security:
32
-
33
- ![Settings](ezpm2gui/screenshots/11-settings.png)
34
-
35
- > See the full visual walkthrough in [https://ezpm2gui.vercel.app/](https://ezpm2gui.vercel.app/) — every screen is annotated with a screenshot.
36
-
37
- ## Features
38
-
39
- - **Real-time process monitoring** - Keep track of all your PM2 processes in real-time
40
- - **Process management** - Start, stop, restart, and delete processes with one click
41
- - **System metrics dashboard** - Monitor CPU, memory usage, and uptime
42
- - **Metrics page with live sparklines** - Per-process rolling 1-hour CPU and memory micro-graphs updated every 3s; switch to History tab for SQLite-backed long-term charts
43
- - **Enhanced log streaming** - View and filter logs from multiple processes simultaneously
44
- - **WebSocket for live updates** - Get instant updates without refreshing
45
- - **Process CPU and memory charts** - Visualize performance metrics over time
46
- - **Filter processes by status or name** - Quickly find the processes you need
47
- - **Dark/light mode** - Fully supported across all pages with Tailwind CSS
48
- - **Cluster management** - Easily scale your Node.js applications
49
- - **Application deployment** - Deploy new applications directly from the UI
50
- - **Ecosystem configuration** - Create and manage your PM2 ecosystem files
51
- - **PM2 modules support** - Manage and configure PM2 modules
52
- - **Cron Jobs** - Schedule and manage automated tasks with visual cron expression builder
53
- - **Remote Server Management** - Connect and manage PM2 on remote servers via SSH
54
- - **Advanced Monitoring Dashboard** - Real-time performance charts with health scoring
55
- - **Tailwind CSS UI** - Sleek, compact, and responsive design with consistent dark/light theming
56
- - **Fully typed with TypeScript** - Robust and maintainable codebase
57
-
58
- ## Detailed Features
59
-
60
- ### Process Monitoring
61
- Monitor all your PM2 processes in real-time with detailed information on CPU usage, memory consumption, uptime, and status. The intuitive interface makes it easy to identify issues at a glance.
62
-
63
- ### Remote Server Management
64
- Connect to and manage PM2 processes on remote servers via secure SSH connections:
65
- - Add multiple remote server connections with SSH credentials
66
- - View and manage processes on remote servers
67
- - Stream logs from remote processes in real-time
68
- - Execute PM2 commands on remote machines
69
- - Encrypted credential storage for security
70
-
71
- ### Cron Jobs
72
- Schedule and automate tasks using PM2's cron restart feature:
73
- - Visual cron expression builder with common presets
74
- - Support for Node.js, Python, Shell, and .NET scripts
75
- - Inline script editor or file-based execution
76
- - Enable/disable jobs without deleting them
77
- - View next execution times and job status
78
-
79
- ### Advanced Monitoring Dashboard
80
- Get deeper insights into your system and process performance:
81
- - Real-time performance charts for CPU, memory, and load
82
- - System health score calculation
83
- - Historical metrics tracking
84
- - Process alerts for high resource usage
85
- - Per-process performance visualization
86
-
87
- ### Application Deployment
88
- Deploy new Node.js applications to PM2 directly from the UI. Configure all the necessary options including:
89
- - Application name and script path
90
- - Working directory
91
- - Number of instances for load balancing
92
- - Execution mode (fork or cluster)
93
- - Auto-restart options
94
- - Memory threshold for restarts
95
- - Environment variables
96
-
97
- ### Cluster Management
98
- Easily scale your Node.js applications with the cluster management interface. Add or remove instances on the fly and switch between fork and cluster execution modes for optimal performance.
99
-
100
- ### Log Streaming
101
- View and filter logs from multiple processes simultaneously with the enhanced log streaming interface. Features include:
102
- - Real-time log updates via WebSocket
103
- - Filtering by process, log level, or content
104
- - Pausing and resuming log streams
105
- - Download logs for offline analysis
106
- - Floating log panel for remote process logs
107
-
108
- ### Ecosystem Configuration
109
- Generate and manage PM2 ecosystem configuration files directly from the UI. This makes it easy to set up complex application deployments and share configurations across your team.
110
-
111
- ### PM2 Modules
112
- Manage and configure PM2 modules to extend the functionality of your PM2 installation. Install, update, and remove modules with a few clicks.
113
-
114
- ### System Metrics
115
- Monitor key system metrics including:
116
- - CPU usage and number of cores
117
- - Memory usage and availability
118
- - System uptime
119
- - Load averages (1, 5, and 15 minutes)
120
-
121
- ### User Interface
122
- EZ PM2 GUI uses Tailwind CSS for a sleek, compact, and fully responsive interface:
123
- - Dark and light mode support across all pages
124
- - Consistent color theming with smooth transitions
125
- - Compact layout with small fonts and reduced spacing for information density
126
- - `PageHeader` and `LogStatusBar` reusable components for a consistent look
127
- - Configure dashboard refresh intervals and log display settings from Settings
128
-
129
- ## Installation
130
-
131
- ### Global Installation
132
-
133
- ```bash
134
- npm install -g ezpm2gui
135
- ```
136
-
137
- ### Local Installation
138
-
139
- ```bash
140
- npm install ezpm2gui
141
- ```
142
-
143
- ## Usage
144
-
145
- ### As a Command Line Tool (Global Installation)
146
-
147
- ```bash
148
- # Start the EZ PM2 GUI web interface
149
- ezpm2gui
150
-
151
- # Start on a specific port
152
- ezpm2gui --port 4000
153
-
154
- # Start bound to all network interfaces
155
- ezpm2gui --host 0.0.0.0
156
-
157
- # Generate a sample PM2 ecosystem config
158
- ezpm2gui-generate-ecosystem
159
- ```
160
-
161
- ### As a Module (Local Installation)
162
-
163
- ```javascript
164
- const ezpm2gui = require('ezpm2gui');
165
-
166
- // Start the server with default options
167
- ezpm2gui.start();
168
-
169
- // Or with custom options
170
- ezpm2gui.start({
171
- port: 3030,
172
- host: '0.0.0.0'
173
- });
174
- ```
175
-
176
- ### Access the UI
177
-
178
- Once started, open your browser and navigate to:
179
-
180
- ```
181
- http://localhost:3001
182
- ```
183
-
184
- ## Requirements
185
-
186
- - Node.js 16.x or later
187
- - PM2 installed globally (`npm install -g pm2`)
188
-
189
- ## Configuration
190
-
191
- EZ PM2 GUI uses environment variables for configuration:
192
-
193
- - `PORT`: The port to run the server on (default: 3001)
194
- - `HOST`: The host to bind to (default: localhost)
195
-
196
- ## Load Balancing with PM2
197
-
198
- EZ PM2 GUI provides an easy interface to manage PM2's load balancing capabilities:
199
-
200
- ### Setting Up Load Balancing
201
-
202
- 1. **Deploy a new application or modify an existing one**:
203
- - Set the number of instances to greater than 1 (or 0/-1 for max instances based on CPU cores)
204
- - Choose "Cluster" as the execution mode for optimal load balancing
205
-
206
- 2. **Manage your cluster**:
207
- - Use the Cluster Management section to scale instances up or down
208
- - Switch between fork and cluster execution modes
209
- - Reload all instances with zero downtime
210
-
211
- ### How Load Balancing Works
212
-
213
- PM2 provides built-in load balancing when you run your Node.js applications in cluster mode with multiple instances:
214
-
215
- - **Cluster Mode**: In this mode, PM2 uses Node.js's cluster module to create multiple worker processes that share the same server port
216
- - **Multiple Instances**: Incoming requests are automatically distributed across your instances
217
- - **Zero Downtime Reloads**: When updating your application, PM2 can reload instances one by one to avoid downtime
218
-
219
- ### Best Practices
220
-
221
- - For CPU-intensive applications, use a number of instances equal to the number of CPU cores
222
- - For I/O-intensive applications, you can use more instances than CPU cores
223
- - Always use cluster mode for load balancing to ensure port sharing between instances
224
- - Use the reload feature instead of restart for zero-downtime deployments
225
-
226
- ## Development
227
-
228
- See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.
229
-
230
- ```bash
231
- # Clone the repository
232
- git clone https://github.com/thechandanbhagat/ezpm2gui.git
233
- cd ezpm2gui
234
-
235
- # Install dependencies and build
236
- ./install.sh # On Linux/macOS
237
- install.bat # On Windows
238
-
239
- # Start in development mode
240
- npm run dev
241
-
242
- # Build the application
243
- npm run build
244
-
245
- # Start the application (production mode)
246
- npm start
247
- ```
248
-
249
- ### Project Structure
250
-
251
- ```
252
- ezpm2gui/
253
- ├── bin/ # CLI entry points
254
- ├── dist/ # Compiled output
255
- ├── docs/ # Documentation
256
- ├── screenshots/ # Application screenshots
257
- ├── scripts/ # Build and utility scripts
258
- ├── src/ # Source code
259
- │ ├── client/ # React frontend
260
- │ │ ├── public/ # Static assets
261
- │ │ └── src/ # React components and logic
262
- │ │ ├── components/ # UI components
263
- │ │ └── types/ # TypeScript types for client
264
- │ ├── server/ # Express backend
265
- │ │ ├── routes/ # API routes
266
- │ │ └── utils/ # Server utilities
267
- │ └── types/ # Shared TypeScript types
268
- └── test/ # Test files
269
- ```
270
-
271
- ## Contributing
272
-
273
- Contributions are welcome! Please feel free to submit a Pull Request.
274
-
275
- 1. Fork the repository
276
- 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
277
- 3. Make your changes
278
- 4. Run the tests to ensure everything works
279
- 5. Commit your changes using our [commit guidelines](./docs/COMMIT_GUIDE.md)
280
- 6. Push to the branch (`git push origin feature/amazing-feature`)
281
- 7. Open a Pull Request
282
-
283
- ### Coding Style
284
-
285
- This project follows standardized TypeScript conventions and uses ESLint for code quality. Before submitting a pull request, please ensure your code follows these guidelines by running:
286
-
287
- ```bash
288
- npm run lint
289
- ```
290
-
291
- ## FAQ
292
-
293
- ### Q: How does EZ PM2 GUI differ from pm2-gui and PM2 Plus?
294
-
295
- A: EZ PM2 GUI is a modern, TypeScript-based alternative to pm2-gui with a more user-friendly interface and additional features. Unlike PM2 Plus, it's completely free and open-source, running locally on your server rather than in the cloud.
296
-
297
- ### Q: Can I use EZ PM2 GUI with PM2 running on a different machine?
298
-
299
- A: Yes, you can configure EZ PM2 GUI to connect to a remote PM2 installation. You'll need to specify the connection details in the application settings.
300
-
301
- ### Q: How do I generate an ecosystem file from my existing processes?
302
-
303
- A: Use the `ezpm2gui-generate-ecosystem` command-line tool, or visit the Ecosystem Config section in the web UI.
304
-
305
- ### Q: Can EZ PM2 GUI handle a large number of processes?
306
-
307
- A: Yes, EZ PM2 GUI is designed to handle dozens of processes efficiently. The UI is optimized to present large amounts of information in a digestible format.
308
-
309
- ### Q: Is EZ PM2 GUI secure?
310
-
311
- A: By default, EZ PM2 GUI binds to localhost for security reasons. If you expose the interface to other machines, consider adding authentication through a reverse proxy like Nginx.
312
-
313
- ## Related Projects
314
-
315
- - [PM2](https://github.com/Unitech/pm2) - The process manager that EZ PM2 GUI works with
316
- - [pm2-gui](https://github.com/Tjatse/pm2-gui) - The original inspiration for this project
317
-
318
- ## License
319
-
320
- GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).
321
-
322
- EZ PM2 GUI interfaces with [PM2](https://github.com/Unitech/pm2), which is licensed under AGPL-3.0. Because this project links PM2 as a library, it is distributed under the same license.
323
-
324
- ## Credits
325
-
326
- Built by [Chandan Bhagat](https://github.com/thechandanbhagat) as a modern alternative to pm2-gui.
327
-
328
- ---
329
-
330
- **Note**: EZ PM2 GUI is not officially affiliated with PM2 or PM2 Plus. It's an independent tool that interfaces with the PM2 process manager.
1
+ # EZ PM2 GUI
2
+
3
+ [![Discord](https://img.shields.io/discord/1234567890?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/ttgc2zqK7b)
4
+
5
+ A modern web-based graphical user interface for the PM2 process manager, built with TypeScript, Tailwind CSS, and React.
6
+
7
+ ## Screenshots
8
+
9
+ **Process Dashboard** — live system metrics and every PM2 process at a glance:
10
+
11
+ ![Process Dashboard](ezpm2gui/screenshots/01-processes.png)
12
+
13
+ **Monitoring** — real-time CPU, memory and uptime per process:
14
+
15
+ ![Process Monitor](ezpm2gui/screenshots/02-monitoring.png)
16
+
17
+ **Metrics (Live)** — rolling 1-hour sparklines per process, updated every 3 seconds:
18
+
19
+ ![Metrics Live](ezpm2gui/screenshots/12-metrics-live.png)
20
+
21
+ **Metrics (History)** — SQLite-backed CPU and memory charts with selectable time range:
22
+
23
+ ![Metrics History](ezpm2gui/screenshots/13-metrics-history.png)
24
+
25
+ **Deploy App** — start new PM2 processes from a structured form:
26
+
27
+ ![Deploy App](ezpm2gui/screenshots/04-deploy-app.png)
28
+
29
+ **Cron Jobs** — schedule recurring tasks without touching crontab:
30
+
31
+ ![Cron Jobs](ezpm2gui/screenshots/08-cron-jobs.png)
32
+
33
+ **Settings** — auto-saved preferences for refresh, logs, theme and security:
34
+
35
+ ![Settings](ezpm2gui/screenshots/11-settings.png)
36
+
37
+ > See the full visual walkthrough in [https://ezpm2gui.vercel.app/](https://ezpm2gui.vercel.app/) — every screen is annotated with a screenshot.
38
+
39
+ ## Features
40
+
41
+ - **Real-time process monitoring** - Keep track of all your PM2 processes in real-time
42
+ - **Process management** - Start, stop, restart, and delete processes with one click
43
+ - **Sidebar quick-actions** *(v1.9.0)* - Per-process restart, start/stop, and logs buttons revealed on hover in the sidebar
44
+ - **System metrics dashboard** - Monitor CPU, memory usage, and uptime
45
+ - **Metrics page with live sparklines** - Per-process rolling 1-hour CPU and memory micro-graphs updated every 3s; switch to History tab for SQLite-backed long-term charts
46
+ - **Enhanced log streaming** - View and filter logs from multiple processes simultaneously
47
+ - **Log search highlighting** *(v1.9.0)* - Search terms are visually highlighted in the log viewer
48
+ - **Log timestamp range filter** *(v1.9.0)* - Filter log output by start/end timestamp with snapshot mode
49
+ - **Remote log polling** *(v1.9.0)* - Logs from remote servers fetched and displayed in real-time
50
+ - **WebSocket for live updates** - Get instant updates without refreshing
51
+ - **Process CPU and memory charts** - Visualize performance metrics over time
52
+ - **Filter processes by status or name** - Quickly find the processes you need
53
+ - **Dark/light mode** - Fully supported across all pages with Tailwind CSS; preference persisted across sessions
54
+ - **Cluster management** - Easily scale your Node.js applications
55
+ - **Application deployment** - Deploy new applications directly from the UI
56
+ - **Ecosystem configuration** - Create and manage your PM2 ecosystem files
57
+ - **PM2 modules support** - Manage and configure PM2 modules
58
+ - **Cron Jobs** - Schedule and manage automated tasks with visual cron expression builder
59
+ - **Remote Server Management** - Connect and manage PM2 on remote servers via SSH
60
+ - **End-to-end encrypted credentials** *(v1.9.0)* - Remote server passwords encrypted in-browser with RSA-OAEP + AES-256-GCM before transmission
61
+ - **Advanced Monitoring Dashboard** - Real-time performance charts with health scoring
62
+ - **Multi-language support** *(v1.10.0)* - Full i18n with English and Nepali locales; language switcher in the navbar; community-extensible
63
+ - **Tailwind CSS UI** - Sleek, compact, and responsive design with consistent dark/light theming
64
+ - **Fully typed with TypeScript** - Robust and maintainable codebase
65
+
66
+ ## Detailed Features
67
+
68
+ ### Process Monitoring
69
+ Monitor all your PM2 processes in real-time with detailed information on CPU usage, memory consumption, uptime, and status. The intuitive interface makes it easy to identify issues at a glance.
70
+
71
+ ### Multi-Language Support
72
+ EZ PM2 GUI ships with full internationalisation (i18n) powered by `i18next` and `react-i18next`:
73
+ - Every page, component, dialog, toast, and tooltip is fully translated
74
+ - **English** (default) and **Nepali** locales included out of the box
75
+ - Language switcher in the navbar; selection persists across sessions
76
+ - Community-extensible add a new locale by following `CONTRIBUTING_TRANSLATIONS.md`
77
+
78
+ ### Remote Server Management
79
+ Connect to and manage PM2 processes on remote servers via secure SSH connections:
80
+ - Add multiple remote server connections with SSH credentials
81
+ - View and manage processes on remote servers
82
+ - Stream logs from remote processes in real-time with polling
83
+ - Execute PM2 commands on remote machines
84
+ - **End-to-end credential encryption** passwords are encrypted client-side (RSA-OAEP + AES-256-GCM hybrid scheme) before transmission; the server never sees plaintext passwords in transit
85
+
86
+ ### Cron Jobs
87
+ Schedule and automate tasks using PM2's cron restart feature:
88
+ - Visual cron expression builder with common presets
89
+ - Support for Node.js, Python, Shell, and .NET scripts
90
+ - Inline script editor or file-based execution
91
+ - Enable/disable jobs without deleting them
92
+ - View next execution times and job status
93
+
94
+ ### Advanced Monitoring Dashboard
95
+ Get deeper insights into your system and process performance:
96
+ - Real-time performance charts for CPU, memory, and load
97
+ - System health score calculation
98
+ - Historical metrics tracking
99
+ - Process alerts for high resource usage
100
+ - Per-process performance visualization
101
+
102
+ ### Application Deployment
103
+ Deploy new Node.js applications to PM2 directly from the UI. Configure all the necessary options including:
104
+ - Application name and script path
105
+ - Working directory
106
+ - Number of instances for load balancing
107
+ - Execution mode (fork or cluster)
108
+ - Auto-restart options
109
+ - Memory threshold for restarts
110
+ - Environment variables
111
+
112
+ ### Cluster Management
113
+ Easily scale your Node.js applications with the cluster management interface. Add or remove instances on the fly and switch between fork and cluster execution modes for optimal performance.
114
+
115
+ ### Log Streaming
116
+ View and filter logs from multiple processes simultaneously with the enhanced log streaming interface. Features include:
117
+ - Real-time log updates via WebSocket
118
+ - **Search with visual highlighting** — matched terms are highlighted inline
119
+ - **Timestamp range filter** — narrow logs to a start/end time window with snapshot mode (polling pauses while filter is active)
120
+ - Filtering by process, log level, or content
121
+ - Pausing and resuming log streams
122
+ - Download logs for offline analysis
123
+ - Floating log panel for remote process logs
124
+ - Remote server log polling
125
+
126
+ ### Ecosystem Configuration
127
+ Generate and manage PM2 ecosystem configuration files directly from the UI. This makes it easy to set up complex application deployments and share configurations across your team.
128
+
129
+ ### PM2 Modules
130
+ Manage and configure PM2 modules to extend the functionality of your PM2 installation. Install, update, and remove modules with a few clicks.
131
+
132
+ ### System Metrics
133
+ Monitor key system metrics including:
134
+ - CPU usage and number of cores
135
+ - Memory usage and availability
136
+ - System uptime
137
+ - Load averages (1, 5, and 15 minutes)
138
+
139
+ ### User Interface
140
+ EZ PM2 GUI uses Tailwind CSS for a sleek, compact, and fully responsive interface:
141
+ - Dark and light mode support across all pages
142
+ - Consistent color theming with smooth transitions
143
+ - Compact layout with small fonts and reduced spacing for information density
144
+ - `PageHeader` and `LogStatusBar` reusable components for a consistent look
145
+ - Configure dashboard refresh intervals and log display settings from Settings
146
+
147
+ ## Installation
148
+
149
+ ### Global Installation
150
+
151
+ ```bash
152
+ npm install -g ezpm2gui
153
+ ```
154
+
155
+ ### Local Installation
156
+
157
+ ```bash
158
+ npm install ezpm2gui
159
+ ```
160
+
161
+ ## Usage
162
+
163
+ ### As a Command Line Tool (Global Installation)
164
+
165
+ ```bash
166
+ # Start the EZ PM2 GUI web interface
167
+ ezpm2gui
168
+
169
+ # Start on a specific port
170
+ ezpm2gui --port 4000
171
+
172
+ # Start bound to all network interfaces
173
+ ezpm2gui --host 0.0.0.0
174
+
175
+ # Generate a sample PM2 ecosystem config
176
+ ezpm2gui-generate-ecosystem
177
+ ```
178
+
179
+ ### As a Module (Local Installation)
180
+
181
+ ```javascript
182
+ const ezpm2gui = require('ezpm2gui');
183
+
184
+ // Start the server with default options
185
+ ezpm2gui.start();
186
+
187
+ // Or with custom options
188
+ ezpm2gui.start({
189
+ port: 3030,
190
+ host: '0.0.0.0'
191
+ });
192
+ ```
193
+
194
+ ### Access the UI
195
+
196
+ Once started, open your browser and navigate to:
197
+
198
+ ```
199
+ http://localhost:3101
200
+ ```
201
+
202
+ ## Requirements
203
+
204
+ - Node.js 16.x or later
205
+ - PM2 installed globally (`npm install -g pm2`)
206
+
207
+ ## Configuration
208
+
209
+ EZ PM2 GUI uses environment variables for configuration:
210
+
211
+ - `PORT`: The port to run the server on (default: `3101`)
212
+ - `HOST`: The host to bind to (default: `localhost`)
213
+
214
+ You can set these in a `.env` file at the project root (create it if it doesn't exist):
215
+
216
+ ```env
217
+ # .env
218
+ PORT=3102
219
+ HOST=localhost
220
+ ```
221
+
222
+ For the React client to connect to the correct port during a production build, also set:
223
+
224
+ ```env
225
+ # src/client/.env
226
+ REACT_APP_API_URL=http://localhost:3102
227
+ ```
228
+
229
+ ## Load Balancing with PM2
230
+
231
+ EZ PM2 GUI provides an easy interface to manage PM2's load balancing capabilities:
232
+
233
+ ### Setting Up Load Balancing
234
+
235
+ 1. **Deploy a new application or modify an existing one**:
236
+ - Set the number of instances to greater than 1 (or 0/-1 for max instances based on CPU cores)
237
+ - Choose "Cluster" as the execution mode for optimal load balancing
238
+
239
+ 2. **Manage your cluster**:
240
+ - Use the Cluster Management section to scale instances up or down
241
+ - Switch between fork and cluster execution modes
242
+ - Reload all instances with zero downtime
243
+
244
+ ### How Load Balancing Works
245
+
246
+ PM2 provides built-in load balancing when you run your Node.js applications in cluster mode with multiple instances:
247
+
248
+ - **Cluster Mode**: In this mode, PM2 uses Node.js's cluster module to create multiple worker processes that share the same server port
249
+ - **Multiple Instances**: Incoming requests are automatically distributed across your instances
250
+ - **Zero Downtime Reloads**: When updating your application, PM2 can reload instances one by one to avoid downtime
251
+
252
+ ### Best Practices
253
+
254
+ - For CPU-intensive applications, use a number of instances equal to the number of CPU cores
255
+ - For I/O-intensive applications, you can use more instances than CPU cores
256
+ - Always use cluster mode for load balancing to ensure port sharing between instances
257
+ - Use the reload feature instead of restart for zero-downtime deployments
258
+
259
+ ## Development
260
+
261
+ See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.
262
+
263
+ ```bash
264
+ # Clone the repository
265
+ git clone https://github.com/thechandanbhagat/ezpm2gui.git
266
+ cd ezpm2gui
267
+
268
+ # Install dependencies and build
269
+ ./install.sh # On Linux/macOS
270
+ install.bat # On Windows
271
+
272
+ # Start in development mode
273
+ npm run dev
274
+
275
+ # Build the application
276
+ npm run build
277
+
278
+ # Start the application (production mode)
279
+ npm start
280
+ ```
281
+
282
+ ### Project Structure
283
+
284
+ ```
285
+ ezpm2gui/
286
+ ├── bin/ # CLI entry points
287
+ ├── dist/ # Compiled output
288
+ ├── docs/ # Documentation
289
+ ├── screenshots/ # Application screenshots
290
+ ├── scripts/ # Build and utility scripts
291
+ ├── src/ # Source code
292
+ │ ├── client/ # React frontend
293
+ │ │ ├── public/ # Static assets
294
+ │ │ └── src/ # React components and logic
295
+ │ │ ├── components/ # UI components
296
+ │ │ └── types/ # TypeScript types for client
297
+ │ ├── server/ # Express backend
298
+ │ │ ├── routes/ # API routes
299
+ │ │ └── utils/ # Server utilities
300
+ │ └── types/ # Shared TypeScript types
301
+ └── test/ # Test files
302
+ ```
303
+
304
+ ## Contributing
305
+
306
+ Contributions are welcome! Please feel free to submit a Pull Request.
307
+
308
+ 1. Fork the repository
309
+ 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
310
+ 3. Make your changes
311
+ 4. Run the tests to ensure everything works
312
+ 5. Commit your changes using our [commit guidelines](./docs/COMMIT_GUIDE.md)
313
+ 6. Push to the branch (`git push origin feature/amazing-feature`)
314
+ 7. Open a Pull Request
315
+
316
+ ### Coding Style
317
+
318
+ This project follows standardized TypeScript conventions and uses ESLint for code quality. Before submitting a pull request, please ensure your code follows these guidelines by running:
319
+
320
+ ```bash
321
+ npm run lint
322
+ ```
323
+
324
+ ## FAQ
325
+
326
+ ### Q: How does EZ PM2 GUI differ from pm2-gui and PM2 Plus?
327
+
328
+ A: EZ PM2 GUI is a modern, TypeScript-based alternative to pm2-gui with a more user-friendly interface and additional features. Unlike PM2 Plus, it's completely free and open-source, running locally on your server rather than in the cloud.
329
+
330
+ ### Q: Can I use EZ PM2 GUI with PM2 running on a different machine?
331
+
332
+ A: Yes, you can configure EZ PM2 GUI to connect to a remote PM2 installation. You'll need to specify the connection details in the application settings.
333
+
334
+ ### Q: How do I generate an ecosystem file from my existing processes?
335
+
336
+ A: Use the `ezpm2gui-generate-ecosystem` command-line tool, or visit the Ecosystem Config section in the web UI.
337
+
338
+ ### Q: Can EZ PM2 GUI handle a large number of processes?
339
+
340
+ A: Yes, EZ PM2 GUI is designed to handle dozens of processes efficiently. The UI is optimized to present large amounts of information in a digestible format.
341
+
342
+ ### Q: Is EZ PM2 GUI secure?
343
+
344
+ A: By default, EZ PM2 GUI binds to localhost for security reasons. If you expose the interface to other machines, consider adding authentication through a reverse proxy like Nginx.
345
+
346
+ ## Related Projects
347
+
348
+ - [PM2](https://github.com/Unitech/pm2) - The process manager that EZ PM2 GUI works with
349
+ - [pm2-gui](https://github.com/Tjatse/pm2-gui) - The original inspiration for this project
350
+
351
+ ## License
352
+
353
+ GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).
354
+
355
+ EZ PM2 GUI interfaces with [PM2](https://github.com/Unitech/pm2), which is licensed under AGPL-3.0. Because this project links PM2 as a library, it is distributed under the same license.
356
+
357
+ ## Credits
358
+
359
+ Built by [Chandan Bhagat](https://github.com/thechandanbhagat) as a modern alternative to pm2-gui.
360
+
361
+ ---
362
+
363
+ **Note**: EZ PM2 GUI is not officially affiliated with PM2 or PM2 Plus. It's an independent tool that interfaces with the PM2 process manager.