# EZ PM2 GUI

[![Discord](https://img.shields.io/discord/1234567890?logo=discord&logoColor=white&label=Discord&color=5865F2)](https://discord.gg/ttgc2zqK7b)

🌐 **Available Languages**: [English](README.md) | [中文](README_zh.md)

A modern web-based graphical user interface for the PM2 process manager, built with TypeScript, Tailwind CSS, and React.

## Previous GitHub Releases

- [v1.11.1](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.11.1)
- [v1.10.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.10.0)
- [v1.9.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.9.0)
- [v1.8.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.8.0)
- [v1.6.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.6.0)
- [v1.5.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.5.0)
- [v1.4.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.4.0)
- [v1.3.2](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.3.2)
- [v1.3.0](https://github.com/thechandanbhagat/ezpm2gui/releases/tag/v1.3.0)

## Screenshots

**Process Dashboard** — live system metrics and every PM2 process at a glance:

![Process Dashboard](ezpm2gui/screenshots/01-processes.png)

**Monitoring** — real-time CPU, memory and uptime per process:

![Process Monitor](ezpm2gui/screenshots/02-monitoring.png)

**Metrics (Live)** — rolling 1-hour sparklines per process, updated every 3 seconds:

![Metrics Live](ezpm2gui/screenshots/12-metrics-live.png)

**Metrics (History)** — SQLite-backed CPU and memory charts with selectable time range:

![Metrics History](ezpm2gui/screenshots/13-metrics-history.png)

**Deploy App** — start new PM2 processes from a structured form:

![Deploy App](ezpm2gui/screenshots/04-deploy-app.png)

**Cron Jobs** — schedule recurring tasks without touching crontab:

![Cron Jobs](ezpm2gui/screenshots/08-cron-jobs.png)

**Settings** — auto-saved preferences for refresh, logs, theme and security:

![Settings](ezpm2gui/screenshots/11-settings.png)

> See the full visual walkthrough in [https://ezpm2gui.vercel.app/](https://ezpm2gui.vercel.app/) — every screen is annotated with a screenshot.

## Features

- **Real-time process monitoring** - Keep track of all your PM2 processes in real-time
- **Process management** - Start, stop, restart, and delete processes with one click
- **Sidebar quick-actions** *(v1.9.0)* - Per-process restart, start/stop, and logs buttons revealed on hover in the sidebar
- **System metrics dashboard** - Monitor CPU, memory usage, and uptime
- **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
- **Enhanced log streaming** - View and filter logs from multiple processes simultaneously
- **Log search highlighting** *(v1.9.0)* - Search terms are visually highlighted in the log viewer
- **Log timestamp range filter** *(v1.9.0)* - Filter log output by start/end timestamp with snapshot mode
- **Remote log polling** *(v1.9.0)* - Logs from remote servers fetched and displayed in real-time
- **WebSocket for live updates** - Get instant updates without refreshing
- **Process CPU and memory charts** - Visualize performance metrics over time
- **Filter processes by status or name** - Quickly find the processes you need
- **Dark/light mode** *(v1.11.1)* - Fully supported across all pages with Tailwind CSS; preference and accent color persisted across sessions
- **Docker support** *(v1.11.1)* - Official `Dockerfile` and `.dockerignore` for containerised deployments
- **Cluster management** - Easily scale your Node.js applications
- **Application deployment** - Deploy new applications directly from the UI
- **Ecosystem configuration** - Create and manage your PM2 ecosystem files
- **PM2 modules support** - Manage and configure PM2 modules
- **Cron Jobs** - Schedule and manage automated tasks with visual cron expression builder
- **Remote Server Management** - Connect and manage PM2 on remote servers via SSH
- **End-to-end encrypted credentials** *(v1.9.0)* - Remote server passwords encrypted in-browser with RSA-OAEP + AES-256-GCM before transmission
- **Advanced Monitoring Dashboard** - Real-time performance charts with health scoring
- **Multi-language support** *(v1.11.0)* - Full i18n with English, Nepali, and Chinese locales; language switcher in the navbar; community-extensible
- **Live metrics sparklines** *(v1.11.1)* - Per-process rolling 1-hour CPU and memory micro-graphs; switch to History tab for SQLite-backed long-term charts
- **Tailwind CSS UI** - Sleek, compact, and responsive design with consistent dark/light theming
- **Fully typed with TypeScript** - Robust and maintainable codebase

## Detailed Features

### Process Monitoring
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.

### Multi-Language Support
EZ PM2 GUI ships with full internationalisation (i18n) powered by `i18next` and `react-i18next`:
- Every page, component, dialog, toast, and tooltip is fully translated
- **English** (default) and **Nepali** locales included out of the box
- Language switcher in the navbar; selection persists across sessions
- Community-extensible — add a new locale by following `CONTRIBUTING_TRANSLATIONS.md`

### Remote Server Management
Connect to and manage PM2 processes on remote servers via secure SSH connections:
- Add multiple remote server connections with SSH credentials
- View and manage processes on remote servers
- Stream logs from remote processes in real-time with polling
- Execute PM2 commands on remote machines
- **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

### Cron Jobs
Schedule and automate tasks using PM2's cron restart feature:
- Visual cron expression builder with common presets
- Support for Node.js, Python, Shell, and .NET scripts
- Inline script editor or file-based execution
- Enable/disable jobs without deleting them
- View next execution times and job status

### Advanced Monitoring Dashboard
Get deeper insights into your system and process performance:
- Real-time performance charts for CPU, memory, and load
- System health score calculation
- Historical metrics tracking
- Process alerts for high resource usage
- Per-process performance visualization

### Application Deployment
Deploy new Node.js applications to PM2 directly from the UI. Configure all the necessary options including:
- Application name and script path
- Working directory
- Number of instances for load balancing
- Execution mode (fork or cluster)
- Auto-restart options
- Memory threshold for restarts
- Environment variables

### Cluster Management
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.

### Log Streaming
View and filter logs from multiple processes simultaneously with the enhanced log streaming interface. Features include:
- Real-time log updates via WebSocket
- **Search with visual highlighting** — matched terms are highlighted inline
- **Timestamp range filter** — narrow logs to a start/end time window with snapshot mode (polling pauses while filter is active)
- Filtering by process, log level, or content
- Pausing and resuming log streams
- Download logs for offline analysis
- Floating log panel for remote process logs
- Remote server log polling

### Ecosystem Configuration
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.

### PM2 Modules
Manage and configure PM2 modules to extend the functionality of your PM2 installation. Install, update, and remove modules with a few clicks.

### System Metrics
Monitor key system metrics including:
- CPU usage and number of cores
- Memory usage and availability
- System uptime
- Load averages (1, 5, and 15 minutes)

### User Interface
EZ PM2 GUI uses Tailwind CSS for a sleek, compact, and fully responsive interface:
- Dark and light mode support across all pages
- Consistent color theming with smooth transitions
- Compact layout with small fonts and reduced spacing for information density
- `PageHeader` and `LogStatusBar` reusable components for a consistent look
- Configure dashboard refresh intervals and log display settings from Settings

## Installation

### Global Installation

```bash
npm install -g ezpm2gui
```

### Local Installation

```bash
npm install ezpm2gui
```

## Usage

### As a Command Line Tool (Global Installation)

```bash
# Start the EZ PM2 GUI web interface
ezpm2gui

# Start on a specific port
ezpm2gui --port 4000

# Start bound to all network interfaces
ezpm2gui --host 0.0.0.0

# Generate a sample PM2 ecosystem config
ezpm2gui-generate-ecosystem
```

### As a Module (Local Installation)

```javascript
const ezpm2gui = require('ezpm2gui');

// Start the server with default options
ezpm2gui.start();

// Or with custom options
ezpm2gui.start({
  port: 3030,
  host: '0.0.0.0'
});
```

### Access the UI

Once started, open your browser and navigate to:

```
http://localhost:3101
```

## Requirements

- Node.js 16.x or later
- PM2 installed globally (`npm install -g pm2`)

## Configuration

EZ PM2 GUI uses environment variables for configuration:

- `PORT`: The port to run the server on (default: `3101`)
- `HOST`: The host to bind to (default: `localhost`)

You can set these in a `.env` file at the project root (create it if it doesn't exist):

```env
# .env
PORT=3102
HOST=localhost
```

For the React client to connect to the correct port during a production build, also set:

```env
# src/client/.env
REACT_APP_API_URL=http://localhost:3102
```

## Load Balancing with PM2

EZ PM2 GUI provides an easy interface to manage PM2's load balancing capabilities:

### Setting Up Load Balancing

1. **Deploy a new application or modify an existing one**: 
   - Set the number of instances to greater than 1 (or 0/-1 for max instances based on CPU cores)
   - Choose "Cluster" as the execution mode for optimal load balancing

2. **Manage your cluster**:
   - Use the Cluster Management section to scale instances up or down
   - Switch between fork and cluster execution modes
   - Reload all instances with zero downtime

### How Load Balancing Works

PM2 provides built-in load balancing when you run your Node.js applications in cluster mode with multiple instances:

- **Cluster Mode**: In this mode, PM2 uses Node.js's cluster module to create multiple worker processes that share the same server port
- **Multiple Instances**: Incoming requests are automatically distributed across your instances
- **Zero Downtime Reloads**: When updating your application, PM2 can reload instances one by one to avoid downtime

### Best Practices

- For CPU-intensive applications, use a number of instances equal to the number of CPU cores
- For I/O-intensive applications, you can use more instances than CPU cores
- Always use cluster mode for load balancing to ensure port sharing between instances
- Use the reload feature instead of restart for zero-downtime deployments

## Development

See [DEVELOPMENT.md](DEVELOPMENT.md) for detailed development instructions.

```bash
# Clone the repository
git clone https://github.com/thechandanbhagat/ezpm2gui.git
cd ezpm2gui

# Install dependencies and build
./install.sh   # On Linux/macOS
install.bat    # On Windows

# Start in development mode
npm run dev

# Build the application
npm run build

# Start the application (production mode)
npm start
```

### Project Structure

```
ezpm2gui/
├── bin/                 # CLI entry points
├── dist/                # Compiled output
├── docs/                # Documentation
├── screenshots/         # Application screenshots
├── scripts/             # Build and utility scripts
├── src/                 # Source code
│   ├── client/          # React frontend
│   │   ├── public/      # Static assets
│   │   └── src/         # React components and logic
│   │       ├── components/ # UI components
│   │       └── types/   # TypeScript types for client
│   ├── server/          # Express backend
│   │   ├── routes/      # API routes
│   │   └── utils/       # Server utilities
│   └── types/           # Shared TypeScript types
└── test/                # Test files
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Run the tests to ensure everything works
5. Commit your changes using our [commit guidelines](./docs/COMMIT_GUIDE.md)
6. Push to the branch (`git push origin feature/amazing-feature`)
7. Open a Pull Request

### Coding Style

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:

```bash
npm run lint
```

## FAQ

### Q: How does EZ PM2 GUI differ from pm2-gui and PM2 Plus?

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.

### Q: Can I use EZ PM2 GUI with PM2 running on a different machine?

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.

### Q: How do I generate an ecosystem file from my existing processes?

A: Use the `ezpm2gui-generate-ecosystem` command-line tool, or visit the Ecosystem Config section in the web UI.

### Q: Can EZ PM2 GUI handle a large number of processes?

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.

### Q: Is EZ PM2 GUI secure?

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.

## Related Projects

- [PM2](https://github.com/Unitech/pm2) - The process manager that EZ PM2 GUI works with
- [pm2-gui](https://github.com/Tjatse/pm2-gui) - The original inspiration for this project

## License

GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later). See [LICENSE](LICENSE).

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.

## Credits

Built by [Chandan Bhagat](https://github.com/thechandanbhagat) as a modern alternative to pm2-gui.

---

**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.