Pulse/docs/CONFIGURATION.md

⚙️ Configuration Guide

Pulse uses a split-configuration model to ensure security and flexibility.

File	Purpose	Security Level
.env	Authentication & Secrets	🔒 Critical (Read-only by owner)
system.json	General Settings	📝 Standard
nodes.enc	Node Credentials	🔒 Encrypted (AES-256-GCM)
alerts.json	Alert Rules	📝 Standard

All files are located in /etc/pulse/ (Systemd) or /data/ (Docker/Kubernetes).

---

🔐 Authentication (.env)

This file controls access to Pulse. It is never exposed to the UI.

# /etc/pulse/.env

# Admin Credentials (bcrypt hashed)
PULSE_AUTH_USER='admin'
PULSE_AUTH_PASS='$2a$12$...' 

# API Tokens (comma-separated)
API_TOKENS='token1,token2'

Advanced: Automated Setup (Skip UI)

You can pre-configure Pulse by setting environment variables. Plain text credentials are automatically hashed on startup.

# Docker Example
docker run -d \
  -e PULSE_AUTH_USER=admin \
  -e PULSE_AUTH_PASS=secret123 \
  -e API_TOKENS=ci-token,agent-token \
  rcourtman/pulse:latest

Advanced: OIDC / SSO

Configure Single Sign-On in Settings → Security → OIDC, or use environment variables to lock the configuration.

See OIDC Documentation and Proxy Auth for details.

---

🖥️ System Settings (system.json)

Controls runtime behavior like ports, logging, and polling intervals. Most of these can be changed in Settings → System.

Full Configuration Reference

{
  "pvePollingInterval": 10,       // Seconds
  "backendPort": 3000,            // Internal port
  "frontendPort": 7655,           // Public port
  "logLevel": "info",             // debug, info, warn, error
  "logFormat": "auto",            // auto, json, console
  "autoUpdateEnabled": false,     // Enable auto-updates
  "adaptivePollingEnabled": true  // Smart polling for large clusters
}

Common Overrides (Environment Variables)

Environment variables take precedence over system.json.

Variable	Description	Default
FRONTEND_PORT	Public listening port	7655
LOG_LEVEL	Log verbosity (debug, info, warn, error)	info
PULSE_PUBLIC_URL	Public URL for notifications/OIDC	""
ALLOWED_ORIGINS	CORS allowed domains	"" (Same origin)
DISCOVERY_ENABLED	Auto-discover nodes	false
PULSE_AUTH_HIDE_LOCAL_LOGIN	Hide username/password form	false
DEMO_MODE	Enable read-only demo mode	false

Monitoring Overrides

Variable	Description	Default
PVE_POLLING_INTERVAL	PVE metrics polling frequency	10s
PBS_POLLING_INTERVAL	PBS metrics polling frequency	60s
PMG_POLLING_INTERVAL	PMG metrics polling frequency	60s
ENABLE_BACKUP_POLLING	Enable backup job monitoring	true
BACKUP_POLLING_INTERVAL	Backup polling frequency	0 (Auto)
ENABLE_TEMPERATURE_MONITORING	Enable SSH temperature checks	true
SSH_PORT	SSH port for temperature checks	22
ADAPTIVE_POLLING_ENABLED	Enable smart polling for large clusters	false
WEBHOOK_BATCH_DELAY	Delay before sending batched webhooks	10s

---

🔔 Alerts (alerts.json)

Pulse uses a powerful alerting engine with hysteresis (separate trigger/clear thresholds) to prevent flapping.

Managed via UI: Settings → Alerts → Thresholds

Manual Configuration (JSON)

{
  "guestDefaults": {
    "cpu": { "trigger": 90, "clear": 80 },
    "memory": { "trigger": 85, "clear": 72.5 }
  },
  "schedule": {
    "quietHours": {
      "enabled": true,
      "start": "22:00",
      "end": "06:00"
    }
  }
}

---

🔒 HTTPS / TLS

Enable HTTPS by providing certificate files via environment variables.

# Systemd
HTTPS_ENABLED=true
TLS_CERT_FILE=/etc/pulse/cert.pem
TLS_KEY_FILE=/etc/pulse/key.pem

# Docker
docker run -e HTTPS_ENABLED=true \
  -v /path/to/certs:/certs \
  -e TLS_CERT_FILE=/certs/cert.pem \
  -e TLS_KEY_FILE=/certs/key.pem ...

---

🛡️ Security Best Practices

1. Permissions: Ensure .env and nodes.enc are 600 (read/write by owner only).
2. Backups: Back up .env separately from system.json.
3. Tokens: Use scoped API tokens for agents instead of the admin password.