vrr/Pulse
2
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-04-28 03:20:11 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

docs: document TLS certificate file permissions for HTTPS setup

Browse source 
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 2025-11-05 23:08:02 +00:00
parent d28cfed3c7
commit 8ca31003a0
2 changed files with 128 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

59
docs/CONFIGURATION.md
View file

@ -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.