mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-09-24 20:22:53 +00:00
Pulse Monitor
b77df2f2f1
- Add custom JSON payload template support for generic webhooks - Users can now define custom webhook formats with Go template syntax - Fix Telegram webhook issue where chat_id in URL caused 400 errors - Automatically strip chat_id from URL and place in JSON body for Telegram - Add comprehensive webhook documentation with examples - Update API documentation with webhook endpoints Addresses #305
284 lines
8.2 KiB
Markdown
284 lines
8.2 KiB
Markdown
# Pulse for Proxmox
|
|
|
|
[](https://github.com/rcourtman/Pulse/releases/latest)
|
|
[](https://hub.docker.com/r/rcourtman/pulse)
|
|
[](LICENSE)
|
|
|
|
**Real-time monitoring for Proxmox VE and PBS with alerts and webhooks.**
|
|
|
|
|
|
|
|
## 💖 Support This Project
|
|
|
|
[](https://github.com/sponsors/rcourtman)
|
|
[](https://ko-fi.com/rcourtman)
|
|
|
|
## Features
|
|
|
|
- **Auto-Discovery**: Finds Proxmox nodes on your network, one-liner setup via generated scripts
|
|
- **Cluster Support**: Configure one node, monitor entire cluster
|
|
- **Security**: Credentials encrypted at rest, masked in logs, never sent to frontend
|
|
- Live monitoring of VMs, containers, nodes, storage
|
|
- Alerts with email and webhooks (Discord, Slack, Telegram, Teams, ntfy.sh, Gotify)
|
|
- Unified view of PBS backups, PVE backups, and snapshots
|
|
- PBS push mode for firewalled servers
|
|
- Config export/import with encryption and authentication
|
|
- Dark/light themes, responsive design
|
|
- Built with Go for minimal resource usage
|
|
|
|
[Screenshots →](docs/SCREENSHOTS.md)
|
|
|
|
## Quick Start
|
|
|
|
### Install
|
|
|
|
```bash
|
|
# Option A: Proxmox Helper Script (creates LXC container)
|
|
bash -c "$(wget -qLO - https://github.com/community-scripts/ProxmoxVE/raw/main/ct/pulse.sh)"
|
|
|
|
# Option B: Docker
|
|
docker run -d -p 7655:7655 -v pulse_data:/data rcourtman/pulse:latest
|
|
|
|
# Option C: Manual (existing systems)
|
|
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | sudo bash
|
|
```
|
|
|
|
### Configure Nodes
|
|
|
|
1. Open `http://<your-server>:7655`
|
|
2. Go to Settings → Nodes
|
|
3. Discovered nodes appear automatically
|
|
4. Click "Setup Script" next to any node
|
|
5. Run the generated one-liner on that node
|
|
6. Node is configured and monitoring starts
|
|
|
|
The script handles user creation, permissions, token generation, and registration automatically.
|
|
|
|
## Docker
|
|
|
|
### Basic
|
|
```bash
|
|
docker run -d \
|
|
--name pulse \
|
|
-p 7655:7655 \
|
|
-v pulse_data:/data \
|
|
--restart unless-stopped \
|
|
rcourtman/pulse:latest
|
|
```
|
|
|
|
### With Network Discovery
|
|
```bash
|
|
# Specify your LAN subnet for auto-discovery
|
|
docker run -d \
|
|
--name pulse \
|
|
-p 7655:7655 \
|
|
-v pulse_data:/data \
|
|
-e DISCOVERY_SUBNET=192.168.1.0/24 \
|
|
--restart unless-stopped \
|
|
rcourtman/pulse:latest
|
|
```
|
|
|
|
### Docker Compose
|
|
```yaml
|
|
services:
|
|
pulse:
|
|
image: rcourtman/pulse:latest
|
|
container_name: pulse
|
|
ports:
|
|
- "7655:7655"
|
|
volumes:
|
|
- pulse_data:/data
|
|
environment:
|
|
# Network discovery
|
|
# - DISCOVERY_SUBNET=192.168.1.0/24 # Auto-discovery subnet (default: auto-detect)
|
|
|
|
# Ports
|
|
# - PORT=7655 # Backend port (default: 7655)
|
|
# - FRONTEND_PORT=7655 # Frontend port (default: 7655)
|
|
|
|
# Security
|
|
# - API_TOKEN=your-secure-token # API authentication token
|
|
# - ALLOW_UNPROTECTED_EXPORT=false # Allow export without auth (default: false)
|
|
|
|
# Polling & timeouts
|
|
# - POLLING_INTERVAL=5 # Seconds between node checks (default: 5)
|
|
# - CONNECTION_TIMEOUT=10 # Connection timeout in seconds (default: 10)
|
|
|
|
# Updates
|
|
# - UPDATE_CHANNEL=stable # Update channel: stable or rc (default: stable)
|
|
# - AUTO_UPDATE_ENABLED=true # Enable auto-updates (default: true)
|
|
# - AUTO_UPDATE_CHECK_INTERVAL=24 # Hours between update checks (default: 24)
|
|
# - AUTO_UPDATE_TIME=03:00 # Time to install updates HH:MM (default: 03:00)
|
|
|
|
# CORS & logging
|
|
# - ALLOWED_ORIGINS=* # CORS allowed origins (default: *)
|
|
# - LOG_LEVEL=info # Log level: debug/info/warn/error (default: info)
|
|
restart: unless-stopped
|
|
|
|
volumes:
|
|
pulse_data:
|
|
```
|
|
|
|
|
|
## PBS Agent (Push Mode)
|
|
|
|
For isolated PBS servers, see [PBS Agent documentation](docs/PBS-AGENT.md)
|
|
|
|
## Security
|
|
|
|
- Credentials encrypted at rest (AES-256-GCM)
|
|
- Tokens masked in logs
|
|
- Frontend never receives actual credentials
|
|
- Export requires authentication
|
|
|
|
See [Security Documentation](docs/SECURITY.md) for details.
|
|
|
|
## Configuration
|
|
|
|
Quick start - most settings are in the web UI:
|
|
- **Settings → Nodes**: Add/remove Proxmox instances
|
|
- **Settings → System**: Polling intervals, CORS settings
|
|
- **Alerts**: Thresholds and notifications
|
|
|
|
### Email Alerts Configuration
|
|
Configure email notifications in **Settings → Alerts → Email Destinations**
|
|
|
|
#### Supported Providers
|
|
- **Gmail/Google Workspace**: Requires app-specific password
|
|
- **Outlook/Office 365**: Requires app-specific password
|
|
- **Custom SMTP**: Any SMTP server
|
|
|
|
#### Recommended Settings
|
|
- **Port 587 with STARTTLS** (recommended for most providers)
|
|
- **Port 465** for SSL/TLS
|
|
- **Port 25** for unencrypted (not recommended)
|
|
|
|
#### Gmail Setup
|
|
1. Enable 2-factor authentication
|
|
2. Generate app-specific password at https://myaccount.google.com/apppasswords
|
|
3. Use your email as username and app password as password
|
|
4. Server: smtp.gmail.com, Port: 587, Enable STARTTLS
|
|
|
|
#### Outlook Setup
|
|
1. Generate app password at https://account.microsoft.com/security
|
|
2. Use your email as username and app password as password
|
|
3. Server: smtp-mail.outlook.com, Port: 587, Enable STARTTLS
|
|
|
|
For deployment overrides (ports, etc), use environment variables:
|
|
```bash
|
|
# Systemd: sudo systemctl edit pulse-backend
|
|
Environment="FRONTEND_PORT=8080"
|
|
|
|
# Docker: -e FRONTEND_PORT=8080
|
|
```
|
|
|
|
📖 **[Full Configuration Guide →](docs/CONFIGURATION.md)**
|
|
|
|
### Backup/Restore
|
|
|
|
```bash
|
|
# Export (v4.0.3+)
|
|
pulse config export -o backup.enc
|
|
|
|
# Import
|
|
pulse config import -i backup.enc
|
|
```
|
|
|
|
Or use Settings → Security tab in UI.
|
|
|
|
## Updates
|
|
|
|
### Docker
|
|
```bash
|
|
docker pull rcourtman/pulse:latest
|
|
docker stop pulse
|
|
docker rm pulse
|
|
# Run docker run command again
|
|
```
|
|
|
|
### Manual Install
|
|
Settings → System → Check for Updates
|
|
|
|
After updates complete, refresh your browser (Ctrl+F5 or Cmd+Shift+R) to load the new version.
|
|
|
|
## API
|
|
|
|
```bash
|
|
# Status
|
|
curl http://localhost:7655/api/health
|
|
|
|
# Metrics (default time range: 1h)
|
|
curl http://localhost:7655/api/charts
|
|
|
|
# With authentication (if configured)
|
|
curl -H "X-API-Token: your-token" http://localhost:7655/api/health
|
|
```
|
|
|
|
📖 **[Full API Documentation →](docs/API.md)** - Complete endpoint reference with examples
|
|
|
|
## Reverse Proxy
|
|
|
|
Using Pulse behind a reverse proxy? **WebSocket support is required for real-time updates.**
|
|
|
|
See [Reverse Proxy Configuration Guide](docs/REVERSE_PROXY.md) for nginx, Caddy, Apache, Traefik, HAProxy, and Cloudflare Tunnel configurations.
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
- Check Proxmox API is accessible (port 8006/8007)
|
|
- Verify credentials have PVEAuditor role minimum
|
|
- For PBS: ensure API token has Datastore.Audit permission
|
|
|
|
### High CPU/Memory
|
|
- Reduce polling interval in Settings
|
|
- Check number of monitored nodes
|
|
- Disable unused features (backups, snapshots)
|
|
|
|
### Logs
|
|
```bash
|
|
# Docker
|
|
docker logs pulse
|
|
|
|
# Manual
|
|
journalctl -u pulse -f
|
|
```
|
|
|
|
## Documentation
|
|
|
|
- [Configuration Guide](docs/CONFIGURATION.md) - Complete setup and configuration
|
|
- [API Reference](docs/API.md) - REST API endpoints and examples
|
|
- [Webhook Guide](docs/WEBHOOKS.md) - Setting up webhooks and custom payloads
|
|
- [Reverse Proxy Setup](docs/REVERSE_PROXY.md) - nginx, Caddy, Apache, Traefik configs
|
|
- [PBS Agent](docs/PBS-AGENT.md) - Monitoring isolated PBS servers
|
|
- [Security](docs/SECURITY.md) - Security features and best practices
|
|
- [FAQ](docs/FAQ.md) - Common questions and troubleshooting
|
|
- [Migration Guide](docs/MIGRATION_V3_TO_V4.md) - Upgrading from v3 to v4
|
|
|
|
## Security
|
|
|
|
- Credentials stored encrypted (AES-256-GCM)
|
|
- Optional API token authentication
|
|
- Export/import requires passphrase
|
|
- [Security Details →](docs/SECURITY.md)
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Frontend
|
|
cd frontend-modern
|
|
npm install
|
|
npm run dev
|
|
|
|
# Backend
|
|
go run cmd/pulse/*.go
|
|
```
|
|
|
|
## Links
|
|
|
|
- [Releases](https://github.com/rcourtman/Pulse/releases)
|
|
- [Docker Hub](https://hub.docker.com/r/rcourtman/pulse)
|
|
- [Issues](https://github.com/rcourtman/Pulse/issues)
|
|
|
|
## License
|
|
|
|
MIT - See [LICENSE](LICENSE) |