mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-04-29 03:50:18 +00:00
c91b7874ac
Complete documentation overhaul for Pulse v4.24.0 release covering all new features and operational procedures. Documentation Updates (19 files): P0 Release-Critical: - Operations: Rewrote ADAPTIVE_POLLING_ROLLOUT.md as GA operations runbook - Operations: Updated ADAPTIVE_POLLING_MANAGEMENT_ENDPOINTS.md with DEFERRED status - Operations: Enhanced audit-log-rotation.md with scheduler health checks - Security: Updated proxy hardening docs with rate limit defaults - Docker: Added runtime logging and rollback procedures P1 Deployment & Integration: - KUBERNETES.md: Runtime logging config, adaptive polling, post-upgrade verification - PORT_CONFIGURATION.md: Service naming, change tracking via update history - REVERSE_PROXY.md: Rate limit headers, error pass-through, v4.24.0 verification - PROXY_AUTH.md, OIDC.md, WEBHOOKS.md: Runtime logging integration - TROUBLESHOOTING.md, VM_DISK_MONITORING.md, zfs-monitoring.md: Updated workflows Features Documented: - X-RateLimit-* headers for all API responses - Updates rollback workflow (UI & CLI) - Scheduler health API with rich metadata - Runtime logging configuration (no restart required) - Adaptive polling (GA, enabled by default) - Enhanced audit logging - Circuit breakers and dead-letter queue Supporting Changes: - Discovery service enhancements - Config handlers updates - Sensor proxy installer improvements Total Changes: 1,626 insertions(+), 622 deletions(-) Files Modified: 24 (19 docs, 5 code) All documentation is production-ready for v4.24.0 release.
127 lines
3.8 KiB
Markdown
127 lines
3.8 KiB
Markdown
# Port Configuration Guide
|
|
|
|
Pulse supports multiple ways to configure the frontend port (default: 7655).
|
|
|
|
> **Development tip:** The hot-reload scripts (`scripts/dev-hot.sh`, `scripts/hot-dev.sh`, and `make dev-hot`) load `.env`, `.env.local`, and `.env.dev`. Set `FRONTEND_PORT` or `PULSE_DEV_API_PORT` there to run the backend on a different port while keeping the generated `curl` commands and Vite proxy in sync.
|
|
|
|
## Recommended Methods
|
|
|
|
### 1. During Installation (Easiest)
|
|
The installer prompts for the port. To skip the prompt, use:
|
|
```bash
|
|
FRONTEND_PORT=8080 curl -fsSL https://raw.githubusercontent.com/rcourtman/Pulse/main/install.sh | bash
|
|
```
|
|
|
|
### 2. Using systemd override (For existing installations)
|
|
```bash
|
|
sudo systemctl edit pulse
|
|
```
|
|
Add these lines:
|
|
```ini
|
|
[Service]
|
|
Environment="FRONTEND_PORT=8080"
|
|
```
|
|
Then restart: `sudo systemctl restart pulse`
|
|
|
|
### 3. Using system.json (Alternative method)
|
|
Edit `/etc/pulse/system.json`:
|
|
```json
|
|
{
|
|
"frontendPort": 8080
|
|
}
|
|
```
|
|
Then restart: `sudo systemctl restart pulse`
|
|
|
|
### 4. Using environment variables (Docker)
|
|
For Docker deployments:
|
|
```bash
|
|
docker run -e FRONTEND_PORT=8080 -p 8080:8080 rcourtman/pulse:latest
|
|
```
|
|
|
|
## Priority Order
|
|
|
|
Pulse checks for port configuration in this order:
|
|
1. `FRONTEND_PORT` environment variable
|
|
2. `PORT` environment variable (legacy)
|
|
3. `frontendPort` in system.json
|
|
4. Default: 7655
|
|
|
|
Environment variables always override configuration files.
|
|
|
|
## Why not .env?
|
|
|
|
The `/etc/pulse/.env` file is reserved exclusively for authentication credentials:
|
|
- `API_TOKENS` - One or more API authentication tokens (hashed)
|
|
- `API_TOKEN` - Legacy single API token (hashed)
|
|
- `PULSE_AUTH_USER` - Web UI username
|
|
- `PULSE_AUTH_PASS` - Web UI password (hashed)
|
|
|
|
Keeping application configuration separate from authentication credentials:
|
|
- Makes it clear what's a secret vs what's configuration
|
|
- Allows different permission models if needed
|
|
- Follows the principle of separation of concerns
|
|
- Makes it easier to backup/share configs without exposing credentials
|
|
|
|
## Service Name Variations
|
|
|
|
**Important:** Pulse uses different service names depending on the deployment environment:
|
|
|
|
- **Systemd (default):** `pulse.service` or `pulse-backend.service` (legacy)
|
|
- **Hot-dev scripts:** `pulse-hot-dev` (development only)
|
|
- **Kubernetes/Helm:** Deployment `pulse`, Service `pulse` (port configured via Helm values)
|
|
|
|
**To check the active service:**
|
|
```bash
|
|
# Systemd
|
|
systemctl list-units | grep pulse
|
|
systemctl status pulse
|
|
|
|
# Kubernetes
|
|
kubectl -n pulse get svc pulse
|
|
kubectl -n pulse get deploy pulse
|
|
```
|
|
|
|
## Change Tracking (v4.24.0+)
|
|
|
|
Port changes via environment variables or `system.json` take effect immediately after restart. **v4.24.0 records configuration changes in update history**—useful for audit trails and troubleshooting.
|
|
|
|
**To view change history:**
|
|
```bash
|
|
# Via UI
|
|
# Navigate to Settings → System → Updates
|
|
|
|
# Via API
|
|
curl -s http://localhost:7655/api/updates/history | jq '.entries[] | {timestamp, action, status}'
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Port not changing after configuration?
|
|
1. **Check which service name is in use:**
|
|
```bash
|
|
systemctl list-units | grep pulse
|
|
```
|
|
It might be `pulse` (default), `pulse-backend` (legacy), or `pulse-hot-dev` (dev environment) depending on your installation method.
|
|
|
|
2. **Verify the configuration is loaded:**
|
|
```bash
|
|
# Systemd
|
|
sudo systemctl show pulse | grep Environment
|
|
|
|
# Kubernetes
|
|
kubectl -n pulse get deploy pulse -o jsonpath='{.spec.template.spec.containers[0].env}' | jq
|
|
```
|
|
|
|
3. **Check if another process is using the port:**
|
|
```bash
|
|
sudo lsof -i :8080
|
|
```
|
|
|
|
4. **Verify post-restart** (v4.24.0+):
|
|
```bash
|
|
# Check actual listening port
|
|
curl -s http://localhost:7655/api/version | jq
|
|
|
|
# Check update history for restart event
|
|
curl -s http://localhost:7655/api/updates/history?limit=5 | jq
|
|
```
|