⚙️ 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/ (Linux/LXC) or /data/ (Docker).

🔐 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	`info`
`DISCOVERY_ENABLED`	Auto-discover nodes	`false`
`ALLOWED_ORIGINS`	CORS allowed domains	`""` (Same origin)
`PULSE_AUTH_HIDE_LOCAL_LOGIN`	Hide username/password form (useful for SSO)	`false`

🔔 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 / LXC
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

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

3.7 KiB Raw Blame History

⚙️ Configuration Guide

🔐 Authentication (.env)

🖥️ System Settings (system.json)