vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-05-13 15:28:38 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2
Pulse/README.md
Pulse Monitor c38329d284 docs: reorder installation methods - community script first 
Community script is the easiest option for Proxmox users
2025-08-06 12:43:08 +00:00

8.2 KiB
Raw Blame History

Pulse Logo Pulse for Proxmox

GitHub release Docker Pulls License

Real-time monitoring for Proxmox VE and PBS with alerts, webhooks, and a clean web interface.

⚠️ IMPORTANT: Upgrading from v3? See the Migration Guide - automatic upgrades will break your installation!

Pulse Dashboard

Key Features

  • Real-time Monitoring - Live updates for VMs, containers, nodes, and storage via WebSockets
  • Smart Alerts - Configurable thresholds with email and webhook notifications (Discord, Slack, Gotify, Telegram, ntfy.sh, Teams)
  • Alert History - Persistent storage of alert events with detailed metrics and timeline
  • Unified Backups - Single view for PBS backups, PVE backups, and snapshots
  • PBS Push Mode - Monitor isolated/firewalled PBS servers without inbound connections
  • Modern UI - Responsive design with dark/light themes, virtual scrolling, and expandable charts
  • Performance - Built with Go for minimal resource usage, stops polling when no clients connected
  • Secure by Default - Encrypted configuration storage with flexible credential management

View Screenshots →

Support Development

Pulse is a solo hobby project developed in my free time. If you find it useful, your support helps keep me motivated and covers hosting costs.

GitHub Sponsors ko-fi

Quick Start (2 minutes)

Prerequisites

  • Proxmox VE 7.0+ or PBS 2.0+
  • Network access to Proxmox API (ports 8006/8007)

Install Pulse

Choose one method:

# Option A: Proxmox Helper Script - Creates dedicated LXC container (EASIEST)
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"

# Option B: Docker (Multi-arch: AMD64, ARM64, ARMv7)
docker run -d -p 7655:7655 -v pulse_data:/data --restart unless-stopped rcourtman/pulse:latest

# Option C: Manual Install (For existing LXC/VMs)
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | sudo bash

Configure Pulse

  1. Open Pulse in your browser: http://<your-server>:7655
  2. Go to Settings → Nodes → Add Node
  3. Enter your Proxmox credentials
  4. Click Save - Pulse will start monitoring immediately

Configuration

Pulse uses a modern, secure configuration system similar to popular apps like Radarr and Sonarr:

Everything Through the UI

  • All configuration is done via the web interface - no manual file editing needed
  • Settings → Nodes: Add/remove Proxmox instances with a simple form
  • Settings → General: Configure ports, intervals, themes, and more
  • Alerts: Set up thresholds and notification channels
  • Configuration is encrypted and stored securely with proper permissions

Zero Configuration Files

Unlike traditional monitoring tools:

  • No YAML/JSON files to edit
  • No environment variables to set
  • No complex configurations
  • Works immediately after installation

Just open the web UI, add your Proxmox nodes through the interface, and you're done!

Data Storage

  • Docker: All data stored in /data (mount with -v pulse_data:/data)
  • Manual Install: All data stored in /etc/pulse
  • Configuration: Everything is managed through the web UI

Configuration Backup & Migration

Pulse v4.0.3+ supports encrypted configuration export/import for backup and migration:

# Export configuration (prompts for passphrase)
pulse config export -o pulse-backup.enc

# Import on another instance
pulse config import -i pulse-backup.enc

# Automated deployment (CI/CD)
PULSE_PASSPHRASE=secret pulse config import -i backup.enc --force

# Docker with auto-import on first run
docker run -d \
  -v pulse_data:/data \
  -v $(pwd)/pulse-backup.enc:/config.enc:ro \
  -e PULSE_INIT_CONFIG_FILE=/config.enc \
  -e PULSE_INIT_CONFIG_PASSPHRASE=secret \
  rcourtman/pulse:latest

Security Notes:

  • Exports are encrypted with AES-256-GCM using your passphrase
  • Credentials remain encrypted throughout the export/import process
  • API endpoints (/api/config/export, /api/config/import) require API_TOKEN if configured
  • Perfect for Docker deployments and infrastructure as code workflows

For Docker Users

Pulse provides multi-architecture Docker images supporting:

  • linux/amd64 - Intel/AMD 64-bit servers
  • linux/arm64 - 64-bit ARM (Raspberry Pi 4/5, Apple Silicon)
  • linux/arm/v7 - 32-bit ARM (Raspberry Pi 2/3)

The only environment variables needed are for the initial ports if you want to change defaults:

docker run -d -p 8080:8080 \
  -e PULSE_SERVER_FRONTEND_PORT=8080 \
  -v pulse_data:/data \
  --restart unless-stopped \
  rcourtman/pulse:latest

Available Docker tags:

  • rcourtman/pulse:latest - Latest stable release
  • rcourtman/pulse:4 - Latest v4.x release
  • rcourtman/pulse:4.0.0 - Specific version

Once running, all configuration is done through the web UI.

Security

Pulse automatically encrypts and secures all configuration:

  • Credentials are encrypted using AES-256-GCM
  • Configuration files have restricted permissions (0600)
  • No plaintext passwords in config files
  • Encryption keys derived from machine ID

See Security Guide for additional security options.

Webhooks

Pulse supports multiple webhook providers for alerts:

  • Discord - Native Discord webhooks with rich embeds
  • Slack - Slack incoming webhooks
  • Gotify - Self-hosted push notifications
  • Telegram - Telegram bot notifications
  • ntfy.sh - Simple pub-sub notifications
  • Teams - Microsoft Teams incoming webhooks
  • Generic - Any webhook endpoint (JSON POST)

Configure webhooks in Alerts → Destinations → Webhooks.

PBS Agent (Push Mode)

For isolated PBS servers that can't be reached directly:

# On the PBS server:
cd /opt
wget https://github.com/rcourtman/Pulse/releases/latest/download/pulse-pbs-agent.tar.gz
tar xzf pulse-pbs-agent.tar.gz
cd pulse-pbs-agent
./install.sh

Configure the agent to push data to your Pulse instance. See PBS Agent Guide.

Docker Compose

version: '3.8'

services:
  pulse:
    image: rcourtman/pulse:latest  # Multi-arch: AMD64, ARM64, ARMv7
    container_name: pulse
    ports:
      - "7655:7655"
    volumes:
      - pulse_data:/data
    restart: unless-stopped

volumes:
  pulse_data:

After starting, configure everything through the web UI at http://localhost:7655.

Building from Source

# Clone repository
git clone https://github.com/rcourtman/Pulse.git
cd Pulse

# Build backend
go build -o pulse ./cmd/pulse

# Build frontend
cd frontend-modern
npm install
npm run build

# Run
./pulse

Troubleshooting

Common Issues

  1. "Connection refused" error

    • Check firewall rules for port 7655
    • Verify Pulse is running: systemctl status pulse-backend

  2. "Invalid credentials" error

    • Ensure user has at least PVEAuditor role
    • For PBS, user needs DatastoreReader permissions
    • Try token authentication instead of password

  3. No data showing

    • Check browser console for errors
    • Verify Proxmox API is accessible from Pulse server
    • Check Pulse logs: journalctl -u pulse -f

Getting Help

License

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

Acknowledgments

  • Built with Go and SolidJS
  • Icons by Lucide
  • Inspired by the Proxmox community's monitoring needs

Made with ❤️ for the Proxmox community