ezpm2gui 1.8.0 → 1.9.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 (31) hide show
  1. package/README.md +355 -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.2836d066.css +5 -0
  24. package/src/client/build/static/css/main.2836d066.css.map +1 -0
  25. package/src/client/build/static/js/{main.28a4a583.js → main.d5c19622.js} +3 -3
  26. package/src/client/build/static/js/{main.28a4a583.js.map → main.d5c19622.js.map} +1 -1
  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.LICENSE.txt → main.d5c19622.js.LICENSE.txt} +0 -0
package/README.md CHANGED
@@ -1,330 +1,355 @@
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
+ - **Tailwind CSS UI** - Sleek, compact, and responsive design with consistent dark/light theming
63
+ - **Fully typed with TypeScript** - Robust and maintainable codebase
64
+
65
+ ## Detailed Features
66
+
67
+ ### Process Monitoring
68
+ 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.
69
+
70
+ ### Remote Server Management
71
+ Connect to and manage PM2 processes on remote servers via secure SSH connections:
72
+ - Add multiple remote server connections with SSH credentials
73
+ - View and manage processes on remote servers
74
+ - Stream logs from remote processes in real-time with polling
75
+ - Execute PM2 commands on remote machines
76
+ - **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
77
+
78
+ ### Cron Jobs
79
+ Schedule and automate tasks using PM2's cron restart feature:
80
+ - Visual cron expression builder with common presets
81
+ - Support for Node.js, Python, Shell, and .NET scripts
82
+ - Inline script editor or file-based execution
83
+ - Enable/disable jobs without deleting them
84
+ - View next execution times and job status
85
+
86
+ ### Advanced Monitoring Dashboard
87
+ Get deeper insights into your system and process performance:
88
+ - Real-time performance charts for CPU, memory, and load
89
+ - System health score calculation
90
+ - Historical metrics tracking
91
+ - Process alerts for high resource usage
92
+ - Per-process performance visualization
93
+
94
+ ### Application Deployment
95
+ Deploy new Node.js applications to PM2 directly from the UI. Configure all the necessary options including:
96
+ - Application name and script path
97
+ - Working directory
98
+ - Number of instances for load balancing
99
+ - Execution mode (fork or cluster)
100
+ - Auto-restart options
101
+ - Memory threshold for restarts
102
+ - Environment variables
103
+
104
+ ### Cluster Management
105
+ 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.
106
+
107
+ ### Log Streaming
108
+ View and filter logs from multiple processes simultaneously with the enhanced log streaming interface. Features include:
109
+ - Real-time log updates via WebSocket
110
+ - **Search with visual highlighting** — matched terms are highlighted inline
111
+ - **Timestamp range filter** — narrow logs to a start/end time window with snapshot mode (polling pauses while filter is active)
112
+ - Filtering by process, log level, or content
113
+ - Pausing and resuming log streams
114
+ - Download logs for offline analysis
115
+ - Floating log panel for remote process logs
116
+ - Remote server log polling
117
+
118
+ ### Ecosystem Configuration
119
+ 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.
120
+
121
+ ### PM2 Modules
122
+ Manage and configure PM2 modules to extend the functionality of your PM2 installation. Install, update, and remove modules with a few clicks.
123
+
124
+ ### System Metrics
125
+ Monitor key system metrics including:
126
+ - CPU usage and number of cores
127
+ - Memory usage and availability
128
+ - System uptime
129
+ - Load averages (1, 5, and 15 minutes)
130
+
131
+ ### User Interface
132
+ EZ PM2 GUI uses Tailwind CSS for a sleek, compact, and fully responsive interface:
133
+ - Dark and light mode support across all pages
134
+ - Consistent color theming with smooth transitions
135
+ - Compact layout with small fonts and reduced spacing for information density
136
+ - `PageHeader` and `LogStatusBar` reusable components for a consistent look
137
+ - Configure dashboard refresh intervals and log display settings from Settings
138
+
139
+ ## Installation
140
+
141
+ ### Global Installation
142
+
143
+ ```bash
144
+ npm install -g ezpm2gui
145
+ ```
146
+
147
+ ### Local Installation
148
+
149
+ ```bash
150
+ npm install ezpm2gui
151
+ ```
152
+
153
+ ## Usage
154
+
155
+ ### As a Command Line Tool (Global Installation)
156
+
157
+ ```bash
158
+ # Start the EZ PM2 GUI web interface
159
+ ezpm2gui
160
+
161
+ # Start on a specific port
162
+ ezpm2gui --port 4000
163
+
164
+ # Start bound to all network interfaces
165
+ ezpm2gui --host 0.0.0.0
166
+
167
+ # Generate a sample PM2 ecosystem config
168
+ ezpm2gui-generate-ecosystem
169
+ ```
170
+
171
+ ### As a Module (Local Installation)
172
+
173
+ ```javascript
174
+ const ezpm2gui = require('ezpm2gui');
175
+
176
+ // Start the server with default options
177
+ ezpm2gui.start();
178
+
179
+ // Or with custom options
180
+ ezpm2gui.start({
181
+ port: 3030,
182
+ host: '0.0.0.0'
183
+ });
184
+ ```
185
+
186
+ ### Access the UI
187
+
188
+ Once started, open your browser and navigate to:
189
+
190
+ ```
191
+ http://localhost:3101
192
+ ```
193
+
194
+ ## Requirements
195
+
196
+ - Node.js 16.x or later
197
+ - PM2 installed globally (`npm install -g pm2`)
198
+
199
+ ## Configuration
200
+
201
+ EZ PM2 GUI uses environment variables for configuration:
202
+
203
+ - `PORT`: The port to run the server on (default: `3101`)
204
+ - `HOST`: The host to bind to (default: `localhost`)
205
+
206
+ You can set these in a `.env` file at the project root (create it if it doesn't exist):
207
+
208
+ ```env
209
+ # .env
210
+ PORT=3102
211
+ HOST=localhost
212
+ ```
213
+
214
+ For the React client to connect to the correct port during a production build, also set:
215
+
216
+ ```env
217
+ # src/client/.env
218
+ REACT_APP_API_URL=http://localhost:3102
219
+ ```
220
+
221
+ ## Load Balancing with PM2
222
+
223
+ EZ PM2 GUI provides an easy interface to manage PM2's load balancing capabilities:
224
+
225
+ ### Setting Up Load Balancing
226
+
227
+ 1. **Deploy a new application or modify an existing one**:
228
+ - Set the number of instances to greater than 1 (or 0/-1 for max instances based on CPU cores)
229
+ - Choose "Cluster" as the execution mode for optimal load balancing
230
+
231
+ 2. **Manage your cluster**:
232
+ - Use the Cluster Management section to scale instances up or down
233
+ - Switch between fork and cluster execution modes
234
+ - Reload all instances with zero downtime
235
+
236
+ ### How Load Balancing Works
237
+
238
+ PM2 provides built-in load balancing when you run your Node.js applications in cluster mode with multiple instances:
239
+
240
+ - **Cluster Mode**: In this mode, PM2 uses Node.js's cluster module to create multiple worker processes that share the same server port
241
+ - **Multiple Instances**: Incoming requests are automatically distributed across your instances
242
+ - **Zero Downtime Reloads**: When updating your application, PM2 can reload instances one by one to avoid downtime
243
+
244
+ ### Best Practices
245
+
246
+ - For CPU-intensive applications, use a number of instances equal to the number of CPU cores
247
+ - For I/O-intensive applications, you can use more instances than CPU cores
248
+ - Always use cluster mode for load balancing to ensure port sharing between instances
249
+ - Use the reload feature instead of restart for zero-downtime deployments
250
+
251
+ ## Development
252
+
253
+ See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.
254
+
255
+ ```bash
256
+ # Clone the repository
257
+ git clone https://github.com/thechandanbhagat/ezpm2gui.git
258
+ cd ezpm2gui
259
+
260
+ # Install dependencies and build
261
+ ./install.sh # On Linux/macOS
262
+ install.bat # On Windows
263
+
264
+ # Start in development mode
265
+ npm run dev
266
+
267
+ # Build the application
268
+ npm run build
269
+
270
+ # Start the application (production mode)
271
+ npm start
272
+ ```
273
+
274
+ ### Project Structure
275
+
276
+ ```
277
+ ezpm2gui/
278
+ ├── bin/ # CLI entry points
279
+ ├── dist/ # Compiled output
280
+ ├── docs/ # Documentation
281
+ ├── screenshots/ # Application screenshots
282
+ ├── scripts/ # Build and utility scripts
283
+ ├── src/ # Source code
284
+ │ ├── client/ # React frontend
285
+ │ │ ├── public/ # Static assets
286
+ │ │ └── src/ # React components and logic
287
+ │ │ ├── components/ # UI components
288
+ │ │ └── types/ # TypeScript types for client
289
+ │ ├── server/ # Express backend
290
+ │ │ ├── routes/ # API routes
291
+ │ │ └── utils/ # Server utilities
292
+ │ └── types/ # Shared TypeScript types
293
+ └── test/ # Test files
294
+ ```
295
+
296
+ ## Contributing
297
+
298
+ Contributions are welcome! Please feel free to submit a Pull Request.
299
+
300
+ 1. Fork the repository
301
+ 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
302
+ 3. Make your changes
303
+ 4. Run the tests to ensure everything works
304
+ 5. Commit your changes using our [commit guidelines](./docs/COMMIT_GUIDE.md)
305
+ 6. Push to the branch (`git push origin feature/amazing-feature`)
306
+ 7. Open a Pull Request
307
+
308
+ ### Coding Style
309
+
310
+ 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:
311
+
312
+ ```bash
313
+ npm run lint
314
+ ```
315
+
316
+ ## FAQ
317
+
318
+ ### Q: How does EZ PM2 GUI differ from pm2-gui and PM2 Plus?
319
+
320
+ 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.
321
+
322
+ ### Q: Can I use EZ PM2 GUI with PM2 running on a different machine?
323
+
324
+ 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.
325
+
326
+ ### Q: How do I generate an ecosystem file from my existing processes?
327
+
328
+ A: Use the `ezpm2gui-generate-ecosystem` command-line tool, or visit the Ecosystem Config section in the web UI.
329
+
330
+ ### Q: Can EZ PM2 GUI handle a large number of processes?
331
+
332
+ 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.
333
+
334
+ ### Q: Is EZ PM2 GUI secure?
335
+
336
+ 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.
337
+
338
+ ## Related Projects
339
+
340
+ - [PM2](https://github.com/Unitech/pm2) - The process manager that EZ PM2 GUI works with
341
+ - [pm2-gui](https://github.com/Tjatse/pm2-gui) - The original inspiration for this project
342
+
343
+ ## License
344
+
345
+ GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).
346
+
347
+ 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.
348
+
349
+ ## Credits
350
+
351
+ Built by [Chandan Bhagat](https://github.com/thechandanbhagat) as a modern alternative to pm2-gui.
352
+
353
+ ---
354
+
355
+ **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.