mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-05-02 13:30:13 +00:00
140 lines
3.7 KiB
Markdown
140 lines
3.7 KiB
Markdown
# ⚙️ 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.
|
|
|
|
```bash
|
|
# /etc/pulse/.env
|
|
|
|
# Admin Credentials (bcrypt hashed)
|
|
PULSE_AUTH_USER='admin'
|
|
PULSE_AUTH_PASS='$2a$12$...'
|
|
|
|
# API Tokens (comma-separated)
|
|
API_TOKENS='token1,token2'
|
|
```
|
|
|
|
<details>
|
|
<summary><strong>Advanced: Automated Setup (Skip UI)</strong></summary>
|
|
|
|
You can pre-configure Pulse by setting environment variables. Plain text credentials are automatically hashed on startup.
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
</details>
|
|
|
|
<details>
|
|
<summary><strong>Advanced: OIDC / SSO</strong></summary>
|
|
|
|
Configure Single Sign-On in **Settings → Security → OIDC**, or use environment variables to lock the configuration.
|
|
|
|
See [OIDC Documentation](OIDC.md) and [Proxy Auth](PROXY_AUTH.md) for details.
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🖥️ System Settings (`system.json`)
|
|
|
|
Controls runtime behavior like ports, logging, and polling intervals. Most of these can be changed in **Settings → System**.
|
|
|
|
<details>
|
|
<summary><strong>Full Configuration Reference</strong></summary>
|
|
|
|
```json
|
|
{
|
|
"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
|
|
}
|
|
```
|
|
</details>
|
|
|
|
### 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
|
|
|
|
<details>
|
|
<summary><strong>Manual Configuration (JSON)</strong></summary>
|
|
|
|
```json
|
|
{
|
|
"guestDefaults": {
|
|
"cpu": { "trigger": 90, "clear": 80 },
|
|
"memory": { "trigger": 85, "clear": 72.5 }
|
|
},
|
|
"schedule": {
|
|
"quietHours": {
|
|
"enabled": true,
|
|
"start": "22:00",
|
|
"end": "06:00"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
</details>
|
|
|
|
---
|
|
|
|
## 🔒 HTTPS / TLS
|
|
|
|
Enable HTTPS by providing certificate files via environment variables.
|
|
|
|
```bash
|
|
# 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
|
|
|
|
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.
|