docs: document TLS certificate file permissions for HTTPS setup
Add comprehensive documentation for HTTPS/TLS configuration including: - File ownership and permission requirements (pulse user) - Common troubleshooting steps for startup failures - Complete setup examples for systemd and Docker - Validation commands for certificate/key verification Related to discussion #634
This commit is contained in:
rcourtman
parent
d28cfed3c7
commit
8ca31003a0
2 changed files with 128 additions and 1 deletions
|
|
@ -526,8 +526,65 @@ Port configuration should be done via one of these methods:
|
|||
- `PORT` - Legacy port variable (use FRONTEND_PORT instead)
|
||||
|
||||
#### TLS/HTTPS Configuration
|
||||
|
||||
Pulse can serve traffic over HTTPS by configuring TLS certificate and key files.
|
||||
|
||||
**Environment Variables:**
|
||||
- `HTTPS_ENABLED` - Enable HTTPS (true/false)
|
||||
- `TLS_CERT_FILE`, `TLS_KEY_FILE` - Paths to TLS certificate files
|
||||
- `TLS_CERT_FILE` - Path to TLS certificate file (e.g., `/etc/pulse/cert.pem`)
|
||||
- `TLS_KEY_FILE` - Path to TLS private key file (e.g., `/etc/pulse/key.pem`)
|
||||
|
||||
**File Permissions & Ownership:**
|
||||
|
||||
Pulse runs as the `pulse` user in bare metal installations. The certificate and key files must be readable by this user:
|
||||
|
||||
```bash
|
||||
# Set ownership to pulse user
|
||||
sudo chown pulse:pulse /etc/pulse/cert.pem /etc/pulse/key.pem
|
||||
|
||||
# Set appropriate permissions
|
||||
sudo chmod 644 /etc/pulse/cert.pem # Certificate (can be world-readable)
|
||||
sudo chmod 600 /etc/pulse/key.pem # Private key (must be restricted)
|
||||
```
|
||||
|
||||
**Common Issues:**
|
||||
|
||||
- **Service fails to start**: Check that certificate files are owned by the `pulse` user
|
||||
- **Permission denied errors**: Verify file permissions with `ls -l /etc/pulse/*.pem`
|
||||
- **Check logs**: Use `journalctl -u pulse -n 50` to view startup errors
|
||||
|
||||
**Example Configuration:**
|
||||
|
||||
For systemd installations, add environment variables to the service:
|
||||
|
||||
```bash
|
||||
# Edit systemd service
|
||||
sudo systemctl edit pulse
|
||||
|
||||
# Add these lines:
|
||||
[Service]
|
||||
Environment="HTTPS_ENABLED=true"
|
||||
Environment="TLS_CERT_FILE=/etc/pulse/cert.pem"
|
||||
Environment="TLS_KEY_FILE=/etc/pulse/key.pem"
|
||||
|
||||
# Reload and restart
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart pulse
|
||||
```
|
||||
|
||||
For Docker installations, pass environment variables and mount certificate files:
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name pulse \
|
||||
-p 7655:7655 \
|
||||
-e HTTPS_ENABLED=true \
|
||||
-e TLS_CERT_FILE=/data/cert.pem \
|
||||
-e TLS_KEY_FILE=/data/key.pem \
|
||||
-v /path/to/certs:/data \
|
||||
-v pulse-data:/data \
|
||||
rcourtman/pulse:latest
|
||||
```
|
||||
|
||||
> **⚠️ UI Override Warning**: When configuration env vars are set (like `ALLOWED_ORIGINS`), the corresponding UI fields will be disabled with a warning message. Remove the env var and restart to enable UI configuration.
|
||||
|
||||
|
|
|
|||
|
|
@ -191,6 +191,76 @@ systemctl status pulse 2>/dev/null \
|
|||
- Try a test service like webhook.site
|
||||
- Check logs for response codes (temporarily set `LOG_LEVEL=debug` via **Settings → System → Logging** or export `LOG_LEVEL=debug` and restart; review `webhook.delivery` entries, then revert to `info`)
|
||||
|
||||
### HTTPS/TLS Configuration Issues
|
||||
|
||||
#### Pulse fails to start after enabling HTTPS
|
||||
**Symptoms**: Service exits with status code 1, continuous restart attempts, or permission denied errors in logs
|
||||
|
||||
**Common causes and solutions:**
|
||||
|
||||
1. **Certificate files not readable by pulse user** (most common)
|
||||
- Pulse runs as the `pulse` user and needs read access to certificate files
|
||||
- Check file ownership: `ls -l /etc/pulse/*.pem`
|
||||
- Solution:
|
||||
```bash
|
||||
sudo chown pulse:pulse /etc/pulse/cert.pem /etc/pulse/key.pem
|
||||
sudo chmod 644 /etc/pulse/cert.pem # Certificate
|
||||
sudo chmod 600 /etc/pulse/key.pem # Private key
|
||||
```
|
||||
|
||||
2. **Invalid certificate or key file**
|
||||
- Verify certificate format: `openssl x509 -in /etc/pulse/cert.pem -text -noout`
|
||||
- Verify private key: `openssl rsa -in /etc/pulse/key.pem -check -noout`
|
||||
- Ensure certificate and key match:
|
||||
```bash
|
||||
openssl x509 -noout -modulus -in /etc/pulse/cert.pem | openssl md5
|
||||
openssl rsa -noout -modulus -in /etc/pulse/key.pem | openssl md5
|
||||
# Both should output the same hash
|
||||
```
|
||||
|
||||
3. **File paths incorrect**
|
||||
- Verify paths in environment variables match actual file locations
|
||||
- Check for typos in `TLS_CERT_FILE` and `TLS_KEY_FILE`
|
||||
- Use absolute paths, not relative paths
|
||||
|
||||
4. **Check startup logs**
|
||||
```bash
|
||||
# View recent service logs
|
||||
journalctl -u pulse -n 50
|
||||
|
||||
# Follow logs in real-time during restart
|
||||
journalctl -u pulse -f
|
||||
```
|
||||
|
||||
**Complete HTTPS setup example:**
|
||||
```bash
|
||||
# 1. Place certificate files
|
||||
sudo cp mycert.pem /etc/pulse/cert.pem
|
||||
sudo cp mykey.pem /etc/pulse/key.pem
|
||||
|
||||
# 2. Set ownership and permissions
|
||||
sudo chown pulse:pulse /etc/pulse/cert.pem /etc/pulse/key.pem
|
||||
sudo chmod 644 /etc/pulse/cert.pem
|
||||
sudo chmod 600 /etc/pulse/key.pem
|
||||
|
||||
# 3. Configure systemd service
|
||||
sudo systemctl edit pulse
|
||||
# Add:
|
||||
# [Service]
|
||||
# Environment="HTTPS_ENABLED=true"
|
||||
# Environment="TLS_CERT_FILE=/etc/pulse/cert.pem"
|
||||
# Environment="TLS_KEY_FILE=/etc/pulse/key.pem"
|
||||
|
||||
# 4. Reload and restart
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl restart pulse
|
||||
|
||||
# 5. Verify service started successfully
|
||||
sudo systemctl status pulse
|
||||
```
|
||||
|
||||
See [Configuration Guide](CONFIGURATION.md#tlshttps-configuration) for complete HTTPS setup documentation.
|
||||
|
||||
### Temperature Monitoring Issues
|
||||
|
||||
#### Temperature data flickers after adding nodes
|
||||
|
|
|
|||
Loading…
Reference in a new issue