diff --git a/dev-docs/CONFIGURATION.md b/dev-docs/CONFIGURATION.md deleted file mode 100644 index 4de54cc50..000000000 --- a/dev-docs/CONFIGURATION.md +++ /dev/null @@ -1,209 +0,0 @@ -# Pulse Configuration Guide - -Pulse supports a flexible configuration system with multiple sources and clear precedence rules. - -## Configuration Sources (in order of precedence) - -1. **Command-line arguments** (highest priority) -2. **Environment variables** -3. **Configuration file** -4. **Default values** (lowest priority) - -## Quick Start - -### Using Environment Variables - -```bash -# Set custom ports -export PULSE_SERVER_BACKEND_PORT=8080 -export PULSE_SERVER_FRONTEND_PORT=8081 - -# Set log level -export PULSE_LOG_LEVEL=debug - -# Run Pulse -./bin/pulse -``` - -### Using Configuration File - -1. Generate an example configuration file: -```bash -./bin/pulse config init -``` - -2. Edit `pulse.yml` to customize settings - -3. Run Pulse: -```bash -./bin/pulse -``` - -### Using Command-Line Arguments - -```bash -# Override specific settings -./bin/pulse --backend-port=9000 --frontend-port=9001 --log-level=debug - -# Use a custom config file -./bin/pulse --config=/custom/path/pulse.yml -``` - -## Configuration File Formats - -Pulse supports both YAML and JSON configuration files: - -- `/etc/pulse/pulse.yml` (system-wide, YAML) -- `/etc/pulse/pulse.json` (system-wide, JSON) -- `./pulse.yml` (local directory, YAML) -- `./pulse.json` (local directory, JSON) - -### Example YAML Configuration - -```yaml -server: - backend: - port: 3000 - host: "0.0.0.0" - frontend: - port: 7655 - host: "0.0.0.0" - -monitoring: - pollingInterval: 5000 - backupPollingCycles: 10 - -logging: - level: "info" - file: "/var/log/pulse/pulse.log" -``` - -## All Configuration Options - -### Server Settings - -| Setting | ENV Variable | CLI Flag | Default | Description | -|---------|-------------|----------|---------|-------------| -| `server.backend.port` | `PULSE_SERVER_BACKEND_PORT` | `--backend-port` | 3000 | Backend API server port | -| `server.backend.host` | `PULSE_SERVER_BACKEND_HOST` | `--backend-host` | 0.0.0.0 | Backend bind address | -| `server.frontend.port` | `PULSE_SERVER_FRONTEND_PORT` | `--frontend-port` | 7655 | Frontend web UI port | -| `server.frontend.host` | `PULSE_SERVER_FRONTEND_HOST` | `--frontend-host` | 0.0.0.0 | Frontend bind address | - -### Monitoring Settings - -| Setting | ENV Variable | Default | Description | -|---------|-------------|---------|-------------| -| `monitoring.pollingInterval` | `PULSE_MONITORING_POLLING_INTERVAL` | 5000 | Polling interval in milliseconds | -| `monitoring.concurrentPolling` | `PULSE_MONITORING_CONCURRENT_POLLING` | true | Enable concurrent polling | -| `monitoring.backupPollingCycles` | `PULSE_MONITORING_BACKUP_POLLING_CYCLES` | 10 | Poll backups every N cycles | -| `monitoring.metricsRetentionDays` | `PULSE_MONITORING_METRICS_RETENTION_DAYS` | 7 | Days to retain metrics | - -### Logging Settings - -| Setting | ENV Variable | CLI Flag | Default | Description | -|---------|-------------|----------|---------|-------------| -| `logging.level` | `PULSE_LOG_LEVEL` | `--log-level` | info | Log level (debug, info, warn, error) | -| `logging.file` | `PULSE_LOG_FILE` | `--log-file` | /opt/pulse/pulse.log | Log file path | -| `logging.maxSize` | `PULSE_LOG_MAX_SIZE` | - | 100 | Max log file size in MB | -| `logging.maxBackups` | `PULSE_LOG_MAX_BACKUPS` | - | 5 | Number of log files to keep | -| `logging.maxAge` | `PULSE_LOG_MAX_AGE` | - | 30 | Max age in days for log files | -| `logging.compress` | `PULSE_LOG_COMPRESS` | - | true | Compress rotated logs | - -### Security Settings - -| Setting | ENV Variable | Default | Description | -|---------|-------------|---------|-------------| -| `security.apiToken` | `PULSE_API_TOKEN` | "" | API authentication token | -| `security.allowedOrigins` | `PULSE_ALLOWED_ORIGINS` | ["*"] | CORS allowed origins (comma-separated) | -| `security.iframeEmbedding` | `PULSE_IFRAME_EMBEDDING` | SAMEORIGIN | X-Frame-Options header | -| `security.enableAuthentication` | `PULSE_ENABLE_AUTHENTICATION` | false | Enable authentication | - -## Docker Configuration - -When running in Docker, you can use environment variables or mount a config file: - -```yaml -version: '3.8' -services: - pulse: - image: pulse:latest - environment: - - PULSE_SERVER_BACKEND_PORT=8080 - - PULSE_SERVER_FRONTEND_PORT=8081 - - PULSE_LOG_LEVEL=debug - volumes: - - ./pulse.yml:/etc/pulse/pulse.yml - ports: - - "8080:8080" - - "8081:8081" -``` - -## Configuration Commands - -### Generate Example Configuration - -```bash -# Generate YAML config (default) -./bin/pulse config init - -# Generate JSON config -./bin/pulse config init --format=json --output=pulse.json - -# Force overwrite existing file -./bin/pulse config init --force -``` - -### Validate Configuration - -```bash -# Validate default config file -./bin/pulse config validate - -# Validate specific file -./bin/pulse config validate /path/to/pulse.yml - -# Show effective configuration -./bin/pulse config validate --verbose -``` - -## Port Configuration Notes - -1. **Privileged Ports**: Ports below 1024 require root privileges -2. **Port Conflicts**: Pulse will check if ports are available before binding -3. **Firewall**: Remember to update firewall rules when changing ports - -## Best Practices - -1. **Production**: Use a configuration file in `/etc/pulse/` -2. **Development**: Use environment variables or CLI arguments -3. **Docker**: Use environment variables for flexibility -4. **Security**: Always set `apiToken` in production environments -5. **Logging**: Use appropriate log levels (info for production, debug for development) - -## Troubleshooting - -### Configuration Not Loading - -1. Check file permissions: `ls -la /etc/pulse/pulse.yml` -2. Validate syntax: `./bin/pulse config validate` -3. Check logs for errors: `tail -f /opt/pulse/pulse.log` - -### Port Already in Use - -1. Check what's using the port: `sudo lsof -i :PORT` -2. Either stop the conflicting service or choose a different port -3. Update firewall rules if needed - -### Environment Variables Not Working - -1. Ensure correct prefix: `PULSE_` -2. Check spelling and case sensitivity -3. Export variables: `export PULSE_SERVER_BACKEND_PORT=8080` - -## Migration from Old Configuration - -If upgrading from an older version: - -1. Backend port was in main config, now in `server.backend.port` -2. Polling interval now in milliseconds (was seconds) -3. Node configuration remains in separate files (nodes.json) \ No newline at end of file diff --git a/dev-docs/SIMPLIFIED-APPROACH.md b/dev-docs/SIMPLIFIED-APPROACH.md deleted file mode 100644 index bdd4a5466..000000000 --- a/dev-docs/SIMPLIFIED-APPROACH.md +++ /dev/null @@ -1,33 +0,0 @@ -# Pulse Configuration Approach (Simplified) - -Following the successful pattern of apps like Radarr, Sonarr, and Jellyfin, Pulse now uses a simplified configuration approach: - -## How It Works - -1. **Everything Through the UI**: All configuration is done through the web interface -2. **Auto-Secured Config**: The config file is automatically secured with 600 permissions -3. **No Manual Editing**: Users never need to touch config files or environment variables -4. **Zero Setup**: Works out of the box with secure defaults - -## Key Benefits - -- **User Friendly**: Just like Radarr/Sonarr - configure everything in the UI -- **More Secure**: Config file is automatically secured, no risk of misconfigured .env files -- **Simpler**: No need to understand environment variables or file permissions -- **Reliable**: Single source of truth, managed by the application - -## For Advanced Users - -While not recommended, advanced users can still: -- Use environment variables: `${VAR_NAME}` in config values -- Use file references: `file:///path/to/secret` in config values -- Edit the config file directly (changes are picked up on restart) - -But these features are hidden by default - the UI is the primary way to configure Pulse. - -## Implementation - -- Config file at `/etc/pulse/pulse.yml` is automatically secured (mode 0600) -- All settings can be modified through the Settings page -- Credentials are stored in the config file, protected by file permissions -- No external dependencies or complex setup required \ No newline at end of file diff --git a/dev-docs/settings-ui-plan.md b/dev-docs/settings-ui-plan.md deleted file mode 100644 index 5fe613ddb..000000000 --- a/dev-docs/settings-ui-plan.md +++ /dev/null @@ -1,57 +0,0 @@ -# Settings UI Enhancement Plan - -To achieve the "everything through UI" goal like Radarr/Sonarr, the Settings page needs these sections: - -## 1. General Settings -- **Backend Port**: Port for API (default: 3000) -- **Frontend Port**: Port for UI (default: 7655) -- **Polling Interval**: How often to check nodes (seconds) -- **Log Level**: Debug, Info, Warn, Error -- **Metrics Retention**: Days to keep historical data - -## 2. Node Management -- **Add Node** button opens form: - - Node Type: Proxmox VE or PBS - - Name: Friendly name - - Host: URL (https://server:8006) - - Authentication: - - Username/Password OR - - API Token (name + value) - - SSL Verification toggle - - What to Monitor (checkboxes) -- **Edit/Delete** existing nodes -- **Test Connection** button for each node - -## 3. Notifications -- **Email Settings**: - - SMTP Server, Port, TLS - - From address, To addresses - - Username/Password for auth -- **Webhooks**: - - Add/Edit/Delete webhook URLs - - Custom headers - - Test webhook button - -## 4. Alerts -- **Default Thresholds**: - - CPU, Memory, Disk warning levels - - Different defaults for nodes vs guests -- **Alert Schedule**: - - Quiet hours configuration - - Cooldown between alerts - - Alert grouping settings - -## 5. Security -- **API Token**: For external integrations -- **CORS Settings**: Allowed origins -- **Session Settings**: Timeout, etc. - -## Implementation Strategy - -1. Each section gets its own API endpoint -2. Settings are saved to pulse.yml automatically -3. Changes take effect immediately (or after quick restart) -4. No manual file editing required -5. Import/Export settings for backup - -This makes Pulse as user-friendly as the apps you mentioned while maintaining flexibility for power users. \ No newline at end of file