Pulse/docs/CONFIGURATION.md

Pulse Configuration Guide

Configuration Methods

Pulse uses different methods for different types of settings:

1. Web UI Configuration

Most settings are configured through the web interface:

• Nodes:
  • Auto-discovers nodes on your network
  • One-click setup with generated scripts
  • Automatic cluster detection
  • Manual add/remove also available
• Alerts: Set thresholds and notification rules
• Updates: Configure update channels and auto-update
• Security: Export/import encrypted configurations

2. Environment Variables (Deployment Overrides)

Environment variables override UI settings. Use them for Docker/systemd deployments:

Docker Example:

docker run -d \
  -e UPDATE_CHANNEL=rc \
  -e POLLING_INTERVAL=10 \
  -e API_TOKEN=your-secure-token \
  rcourtman/pulse:latest

Systemd Example:

# Edit service
sudo systemctl edit pulse-backend

# Add overrides:
[Service]
Environment="UPDATE_CHANNEL=rc"
Environment="POLLING_INTERVAL=10"

.env File (Optional): You can use a .env file for convenience, but UI settings take precedence:

# Create .env for deployment overrides
sudo nano /etc/pulse/.env
# Add: UPDATE_CHANNEL=rc
sudo systemctl restart pulse-backend

Available variables:

• FRONTEND_PORT - Web UI port
• POLLING_INTERVAL - Node check interval (seconds)
• CONNECTION_TIMEOUT - Connection timeout (seconds)
• UPDATE_CHANNEL - stable or rc
• AUTO_UPDATE_ENABLED - true/false
• AUTO_UPDATE_CHECK_INTERVAL - Hours between checks
• AUTO_UPDATE_TIME - Update time (HH:MM)
• ALLOWED_ORIGINS - CORS origins
• LOG_LEVEL - debug/info/warn/error
• DISCOVERY_SUBNET - Network subnet for auto-discovery (default: auto, e.g., 192.168.0.0/24)

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 at /etc/pulse/.encryption.key with restricted permissions.

File Locations

• Configuration: /etc/pulse/ (or ./data if not writable)
  • system.json - UI-managed settings
  • .encryption.key - Auto-generated encryption key (do not share!)
  • nodes.enc - Encrypted node credentials
  • email.enc - Encrypted email settings
  • .env - Optional deployment overrides (if created)
• Metrics: /etc/pulse/metrics/
• Logs: /etc/pulse/pulse.log

Common Configuration Tasks

Change the Web Port

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

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

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