ProxMox Pulse

A lightweight, responsive ProxMox monitoring application that displays real-time metrics for CPU, memory, network, and disk usage across multiple nodes.

Features

• Real-time monitoring of ProxMox nodes, VMs, and containers
• Dashboard with summary cards for nodes, guests, and resources
• Responsive design that works on desktop and mobile
• WebSocket connection for live updates
• Automatic version display linked to GitHub releases

Versioning

The application version displayed in the header is automatically updated when a new GitHub release is created. This is handled by a GitHub Actions workflow that:

1. Updates the version in the source code when a release is published
2. Updates the package.json files to match the release version
3. Commits and pushes these changes back to the repository

For more details on how to create releases, see the workflow documentation.

Environment Variables

Backend Environment Variables

The backend server uses the following environment variables, which can be set in the .env file:

• PORT: The port on which the server will run (default: 7654)
• NODE_ENV: Set to production for production or development for development
• LOG_LEVEL: Log level (error, warn, info, debug)
• ENABLE_DEV_TOOLS: Enable development tools (true or false)
• IGNORE_SSL_ERRORS: Whether to ignore SSL errors when connecting to ProxMox nodes
• NODE_TLS_REJECT_UNAUTHORIZED: Set to 0 to disable SSL certificate validation (not recommended for production)

Frontend Environment Variables

The frontend can be configured using the following environment variables:

• VITE_API_URL: The URL of the backend API (defaults to the current origin if not specified)

Security Considerations

• For development or internal networks, you can set IGNORE_SSL_ERRORS=true and NODE_TLS_REJECT_UNAUTHORIZED=0
• For production, set these to false and 1 respectively, and ensure proper SSL certificates are installed
• Setting these to true and 0 disables SSL certificate validation and is not secure for production environments

Installation

Development Setup

1. Clone the repository
2. Install dependencies:

   npm install
   

3. Install frontend dependencies:

   cd frontend && npm install
   

4. Create a .env file based on the .env.example file
5. Start the development server:

   ./start-pulse.sh
   

6. Access the application at http://localhost:9513

Production Setup with Docker

1. Clone the repository
2. Copy the example environment file and configure it:

   cp .env.example .env
   

3. Edit the .env file with your ProxMox node details
4. Start the application:

   docker-compose up -d pulse
   

5. Access the application at http://localhost:7654

Quick Start with Docker Hub

The easiest way to get started with Pulse is to use the pre-built Docker image:

1. Create a .env file with your ProxMox node details (see Configuration section)
2. Run the container:

   docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest
   

3. Access the application at http://localhost:7654

Docker Details

The Docker setup uses a production-optimized build that:

• Runs the compiled application with minimal dependencies
• Runs as a non-root user for better security
• Serves both frontend and backend on port 7654
• Exits if startup checks fail (e.g., if it can't connect to your ProxMox nodes)

For development, use ./start-pulse.sh instead of Docker, as it provides:

• Hot-reloading of both frontend and backend
• Source maps for better debugging
• Development tools and detailed logging
• Immediate reflection of code changes

Configuration

The only configuration you need to provide is your ProxMox node details. Create a .env file in the root directory based on the .env.example file:

# ProxMox Node Configuration
# Replace with your ProxMox node details

# Node 1
PROXMOX_NODE_1_NAME=Proxmox Node 1
PROXMOX_NODE_1_HOST=https://proxmox.local:8006
PROXMOX_NODE_1_TOKEN_ID=root@pam!pulse
PROXMOX_NODE_1_TOKEN_SECRET=your-token-secret

# Node 2 (optional)
PROXMOX_NODE_2_NAME=Proxmox Node 2
PROXMOX_NODE_2_HOST=https://proxmox2.local:8006
PROXMOX_NODE_2_TOKEN_ID=root@pam!pulse
PROXMOX_NODE_2_TOKEN_SECRET=your-token-secret

Advanced Configuration

You can customize the application further with these optional settings:

# App Configuration (usually you don't need to change these)
PORT=7654
NODE_ENV=development
LOG_LEVEL=debug
ENABLE_DEV_TOOLS=true
METRICS_HISTORY_MINUTES=60
IGNORE_SSL_ERRORS=true
NODE_TLS_REJECT_UNAUTHORIZED=0

# Polling Intervals (in milliseconds)
NODE_POLLING_INTERVAL_MS=10000
EVENT_POLLING_INTERVAL_MS=2000

The NODE_TLS_REJECT_UNAUTHORIZED=0 setting is particularly important when using self-signed certificates, as it tells Node.js to ignore SSL certificate validation errors. Note that this should only be used in development environments or when you trust your network, as it bypasses security checks.

Important Note on API Tokens

If your ProxMox API token ID contains special characters (like !, @, or %), make sure to properly encode them in your environment variables. In some cases, you may need to escape these characters or enclose the entire token ID in quotes.

For example:

PROXMOX_NODE_1_TOKEN_ID="root@pam!pulse"

Support

If you encounter any issues or have questions, please open an issue on the GitHub repository.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Thanks to the ProxMox team for their excellent virtualization platform
• All contributors who have helped improve this project