Pulse/docs/CONFIGURATION.md

Pulse Configuration Guide

Configuration Methods by Deployment Type

Docker Deployments

Configuration location: /data (volume mount)

• All settings stored in the mounted volume
• Environment variables passed with -e flag
• No .env file support (use docker-compose.yml or -e flags)
• Configuration persists in the volume across container restarts

Setting environment variables:

# Direct run
docker run -d \
  -e FRONTEND_PORT=8080 \
  -e UPDATE_CHANNEL=rc \
  -e API_TOKEN=your-secure-token \
  -v pulse_data:/data \
  rcourtman/pulse:latest

# Or use docker-compose.yml (see README)

LXC/Systemd Deployments (Native Install)

Configuration location: /etc/pulse

• Settings stored in encrypted JSON files
• Environment variables can be set via systemd or .env file
• .env file at /etc/pulse/.env is auto-loaded if present

Setting environment variables - Option 1: Systemd override

# Edit service
sudo systemctl edit pulse-backend

# Add overrides:
[Service]
Environment="FRONTEND_PORT=8080"
Environment="UPDATE_CHANNEL=rc"

Setting environment variables - Option 2: .env file

# Create/edit .env file
sudo nano /etc/pulse/.env

# Add variables:
FRONTEND_PORT=8080
UPDATE_CHANNEL=rc

# Restart service
sudo systemctl restart pulse-backend

Web UI Configuration (Both Deployments)

Most settings are configured through the web interface at http://<server>:7655/settings:

• Nodes: Auto-discovery, one-click setup scripts, cluster detection
• Alerts: Thresholds and notification rules
• Updates: Update channels and auto-update settings
• Security: Export/import encrypted configurations

Environment Variables

Available variables:

Variables that ALWAYS override UI settings:

• FRONTEND_PORT or PORT - Web UI port (default: 7655)
• API_TOKEN - Token for API authentication (overrides UI)
• PULSE_AUTH_USER - Username for web UI authentication (overrides UI)
• PULSE_AUTH_PASS - Password for web UI authentication (overrides UI)
• UPDATE_CHANNEL - stable or rc (overrides UI)
• AUTO_UPDATE_ENABLED - true/false (overrides UI)
• AUTO_UPDATE_CHECK_INTERVAL - Hours between checks (overrides UI)
• AUTO_UPDATE_TIME - Update time HH:MM (overrides UI)
• CONNECTION_TIMEOUT - Connection timeout in seconds (overrides UI)
• ALLOWED_ORIGINS - CORS origins (overrides UI, default: empty = same-origin only)
• LOG_LEVEL - debug/info/warn/error (overrides UI)

Variables that only work if no system.json exists:

• POLLING_INTERVAL - Node check interval in seconds (default: 3)

Other variables:

• DISCOVERY_SUBNET - Network subnet for auto-discovery (default: auto-detect)
• ALLOW_UNPROTECTED_EXPORT - Allow export without auth (default: false)
• PULSE_DEV - Enable development mode features (default: false)

3. Secure Environment Variables

For sensitive data like API tokens and passwords:

# Edit systemd service
sudo systemctl edit pulse-backend

# Add secure environment variables:
[Service]
Environment="API_TOKEN=your-secure-token"
Environment="ALLOW_UNPROTECTED_EXPORT=true"

# Restart service
sudo systemctl restart pulse-backend

Docker users:

docker run -e API_TOKEN=secure-token -p 7655:7655 rcourtman/pulse:latest

Data Storage

Encrypted Storage

All sensitive data is automatically encrypted at rest using AES-256-GCM:

• Node passwords and API tokens
• Email server passwords
• PBS credentials

The encryption key is auto-generated and stored in the data directory with restricted permissions.

File Locations

Docker Container:

• Base directory: /data (mounted volume)
• Config files: /data/*.json, /data/*.enc
• Encryption key: /data/.encryption.key
• Metrics: /data/metrics/
• Logs: Container logs (docker logs pulse)
• No .env file support

LXC/Native Install:

• Base directory: /etc/pulse
• Config files: /etc/pulse/*.json, /etc/pulse/*.enc
• Encryption key: /etc/pulse/.encryption.key
• Metrics: /etc/pulse/metrics/
• Logs: /etc/pulse/pulse.log or journalctl
• Optional: /etc/pulse/.env for env overrides

Files created (both deployments):

• system.json - UI-managed settings
• .encryption.key - Auto-generated encryption key (do not share!)
• nodes.enc - Encrypted node credentials
• email.enc - Encrypted email settings

Common Configuration Tasks

Change the Web Port

Docker:

# Stop existing container
docker stop pulse

# Run with new port
docker run -d --name pulse \
  -e FRONTEND_PORT=8080 \
  -p 8080:8080 \
  -v pulse_data:/data \
  rcourtman/pulse:latest

LXC/Systemd:

echo "FRONTEND_PORT=8080" >> /etc/pulse/.env
sudo systemctl restart pulse-backend

Enable API Authentication

sudo systemctl edit pulse-backend
# Add: Environment="API_TOKEN=your-secure-token"
sudo systemctl restart pulse-backend

Configure for Reverse Proxy

Docker:

docker run -d --name pulse \
  -e ALLOWED_ORIGINS="https://pulse.example.com" \
  -p 7655:7655 \
  -v pulse_data:/data \
  rcourtman/pulse:latest

LXC/Systemd:

echo "ALLOWED_ORIGINS=https://pulse.example.com" >> /etc/pulse/.env
sudo systemctl restart pulse-backend

Enable Debug Logging

echo "LOG_LEVEL=debug" >> /etc/pulse/.env
sudo systemctl restart pulse-backend
tail -f /etc/pulse/pulse.log

Configure Discovery Subnet (Docker)

By default, Docker containers may only discover nodes on the Docker bridge network. To scan your actual network:

docker run -d \
  -e DISCOVERY_SUBNET=192.168.1.0/24 \
  -p 7655:7655 \
  rcourtman/pulse:latest

Replace 192.168.1.0/24 with your actual network subnet.

Security Notes

⚠️ Never put sensitive data in .env files!

• .env files are not encrypted
• Use systemd environment variables for API_TOKEN
• Node credentials are always stored encrypted

Node Setup Details

Auto-Registration Script

The setup script generated for each discovered node:

1. Creates monitoring user (pulse-monitor@pam or pulse-monitor@pbs)
2. Sets minimal permissions (PVEAuditor or Datastore.Audit)
3. Generates API token with timestamp
4. Registers with Pulse automatically
5. Optionally cleans up old tokens

Example:

curl -sSL "http://pulse:7655/api/setup-script?type=pve&host=https%3A%2F%2F192.168.1.10%3A8006" | bash

Manual Setup

If auto-registration isn't suitable, you can still set up manually:

Proxmox VE:

pveum user add pulse-monitor@pam
pveum aclmod / -user pulse-monitor@pam -role PVEAuditor
pveum user token add pulse-monitor@pam pulse-token --privsep 0

PBS:

proxmox-backup-manager user create pulse-monitor@pbs
proxmox-backup-manager acl update / Admin --auth-id pulse-monitor@pbs
proxmox-backup-manager user generate-token pulse-monitor@pbs pulse-token

Reverse Proxy Configuration

Pulse requires WebSocket support for real-time updates. If using a reverse proxy (nginx, Apache, Caddy, etc.), you MUST enable WebSocket proxying.

See the Reverse Proxy Guide for detailed configurations.

Troubleshooting

Port Already in Use

Check what's using the port:

sudo lsof -i :7655

Permission Denied

Ensure Pulse has write access:

sudo chown -R pulse:pulse /etc/pulse

Changes Not Taking Effect

Always restart after configuration changes:

sudo systemctl restart pulse-backend