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

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

Using Docker Compose with Docker Hub

For a more robust setup with Docker Compose:

1. Create a .env file with your ProxMox node details
2. Run using Docker Compose:

   docker-compose up -d pulse
   

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

Standard Installation

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. Run the application:

   npm run pulse
   

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

Docker Deployment

Using Docker Compose (Recommended)

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 using the pre-built Docker Hub image (default):

   docker-compose up -d pulse
   

   Or build from source (uncomment the pulse-build service in docker-compose.yml first):

   # First uncomment the pulse-build service in docker-compose.yml
   docker-compose up -d pulse-build
   

   Or run in development mode with live reloading:

   docker-compose up -d pulse-dev
   

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

Using Docker Directly

1. Build and run the container:

   # Using pre-built image
   docker run -d -p 7654:7654 --env-file .env --name pulse-app rcourtman/pulse:latest
   
   # Building from source (production)
   docker build --target production -t proxmox-pulse:prod .
   docker run -d -p 7654:7654 --env-file .env --name proxmox-pulse proxmox-pulse:prod
   
   # Building from source (development with live reloading)
   docker build --target development -t proxmox-pulse:dev .
   docker run -d -p 7654:7654 -p 9513:9513 --env-file .env --name proxmox-pulse-dev proxmox-pulse:dev
   

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

Docker Image Details

The Docker setup uses a multi-stage build approach with two main targets:

• Production: A lightweight image that runs the compiled application with minimal dependencies and runs as a non-root user for better security.
• Development: A more feature-rich image that includes all development dependencies and tools.

In production mode, the application will exit if startup checks fail (e.g., if it can't connect to your ProxMox nodes). In development mode, it will continue running with warnings, allowing you to troubleshoot connection issues.

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