docs(sensor-proxy): comprehensive config management documentation

Adds complete documentation for the new sensor-proxy config management CLI
implemented in Phase 2. Addresses user-facing aspects of the corruption fix.

**New Documentation:**
- docs/operations/sensor-proxy-config-management.md (469 lines)
  - Complete operations runbook for config management
  - Full CLI reference with examples
  - Migration guide from inline config
  - Architecture explanation
  - Common operational tasks
  - Troubleshooting guide
  - Best practices and automation

**Updated Documentation:**
- cmd/pulse-sensor-proxy/README.md
  - Configuration Management CLI section
  - Allowed Nodes File format
  - Enhanced troubleshooting
  - Config corruption recovery

- docs/TEMPERATURE_MONITORING.md
  - Config validation failure troubleshooting
  - Configuration Management quick reference
  - Cross-links to detailed docs

- docs/TROUBLESHOOTING.md
  - Sensor proxy config validation errors
  - Comprehensive diagnosis steps
  - Automatic and manual recovery

- README.md & docs/README.md
  - Added new runbook to operations index
  - Positioned for discoverability

**Coverage:**
- Both CLI commands fully documented
- Phase 1 & Phase 2 architecture explained
- Migration path from pre-v4.31.1
- Config corruption recovery procedures
- Safe config editing practices
- Automation examples
- Troubleshooting all failure modes

**Documentation Quality:**
- Cross-linked from 5 different documents
- Clear examples for common use cases
- Target audience: system administrators
- Follows project documentation style
- Production-ready

This completes the sensor-proxy config corruption fix by providing users
with comprehensive guidance for the new config management system.

Related to Phase 2 commits 3dc073a28, 804a638ea, 131666bc1
This commit is contained in:
rcourtman 2025-11-19 10:01:33 +00:00
parent d99a855ee7
commit e39c6a3660
6 changed files with 700 additions and 0 deletions

View file

@ -280,6 +280,56 @@ See [Configuration Guide](CONFIGURATION.md#tlshttps-configuration) for complete
### Temperature Monitoring Issues
#### Sensor proxy fails to start (config validation error)
**Symptoms:** Service won't start, logs show "Config validation failed" or "duplicate allowed_nodes blocks detected"
**Diagnosis:**
```bash
# Check service status
sudo systemctl status pulse-sensor-proxy
# Validate config manually
pulse-sensor-proxy config validate
# Look for duplicate blocks
grep -n "allowed_nodes:" /etc/pulse-sensor-proxy/config.yaml
```
**Fix:**
The issue is config corruption from earlier versions. Version 4.31.1+ fixes this automatically:
```bash
# Reinstall to migrate to new config system
curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/scripts/install-sensor-proxy.sh | \
sudo bash -s -- --standalone --pulse-server http://your-pulse:7655
# Verify the fix
pulse-sensor-proxy config validate
sudo systemctl status pulse-sensor-proxy
```
The new config system:
- Separates allowed nodes into `/etc/pulse-sensor-proxy/allowed_nodes.yaml`
- Uses atomic writes with file locking
- Validates config before service startup
- Includes CLI for safe config management
**Manual config management (advanced):**
```bash
# Add nodes to allowed list
pulse-sensor-proxy config set-allowed-nodes --merge 192.168.0.1 --merge node1.local
# Replace entire list
pulse-sensor-proxy config set-allowed-nodes --replace --merge 192.168.0.1
# Validate before restarting
pulse-sensor-proxy config validate
sudo systemctl restart pulse-sensor-proxy
```
See `/opt/pulse/cmd/pulse-sensor-proxy/README.md` for complete CLI documentation.
#### Temperature data flickers after adding nodes
**Symptoms:** Dashboard temperatures alternate between values and `--`, or new nodes never show readings. Proxy logs contain `limiter.rejection` messages.