From 9bc6f6ed647bc6ccde0b2631c0f299eb1f96ce86 Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Wed, 30 Sep 2026 08:17:43 +0100 Subject: [PATCH] Make port troubleshooting safe and deployment-specific Remove the full service-environment dump, which can expose authentication and integration credentials. Explain listener precedence, the separate agent port, systemd reloads, and Docker port recreation without changing the image or deleting persistent data. Keep the shipped guide identical and protect these boundaries with documentation tests. Contract-Neutral: Guidance and verification for existing port configuration only; no runtime, authentication, schema or frontend behaviour changes. Change-source: pulse-maintainer --- docs/TROUBLESHOOTING.md | 32 +++++++++++++++++-- .../public/docs/TROUBLESHOOTING.md | 32 +++++++++++++++++-- .../src/utils/__tests__/docsLinks.test.ts | 22 +++++++++++++ 3 files changed, 80 insertions(+), 6 deletions(-) diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index eaa7e5cebb..1a1102e057 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -58,9 +58,35 @@ screen for this instance and do not paste it into support requests or issue reports. ### Port change didn't take effect -1. Check which service is running: `systemctl status pulse` (legacy installs may use `pulse-backend`). -2. Verify environment override: `systemctl show pulse --property=Environment`. -3. Docker: Ensure you updated the `-p` flag (e.g., `-p 8080:7655`). + +The web UI and API listen on `FRONTEND_PORT` (default `7655`). The deprecated +`PORT` alias applies only when `FRONTEND_PORT` is unset; changing +`frontendPort` in `system.json` has no effect. `PULSE_AGENT_INGEST_PORT` is a +separate agent listener, not the web UI port. See +[Port configuration](CONFIGURATION.md#common-overrides-environment-variables). + +- **Systemd / Proxmox LXC**: identify the active service with + `systemctl is-active pulse` (legacy installs may use `pulse-backend`). Inspect + only the port setting in its managed configuration locally. If you change a + unit or drop-in, run `sudo systemctl daemon-reload`, then restart the affected + service during a suitable maintenance window. For LXC, run these checks inside + the Pulse container, not on the Proxmox host. +- **Docker / Compose**: distinguish the published host port from the listener + inside the container. With the default listener, `8080:7655` exposes the UI on + host port `8080`; changing the host port does not require `FRONTEND_PORT`. + In the repository's Compose file, `PULSE_PORT` controls this host-side mapping. + Save the mapping in your existing Compose project and apply it with + `docker compose up -d pulse`, keeping the same image and mounted data volume. + Restarting an existing container does not apply a new port mapping. For other + container managers, use their recreate/redeploy action while preserving the + data mount; do not delete the volume. +- **Reverse proxy**: check its upstream port and the firewall separately. A + working agent connection on a split-port deployment does not prove that the + web UI is reachable. + +Do not post full service environments, `docker inspect` output or resolved +`docker compose config` output: they can include passwords and tokens. Share +only the relevant port numbers and a redacted error if help is needed. ### "Connection Refused" - Check if Pulse is running. diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md index eaa7e5cebb..1a1102e057 100644 --- a/frontend-modern/public/docs/TROUBLESHOOTING.md +++ b/frontend-modern/public/docs/TROUBLESHOOTING.md @@ -58,9 +58,35 @@ screen for this instance and do not paste it into support requests or issue reports. ### Port change didn't take effect -1. Check which service is running: `systemctl status pulse` (legacy installs may use `pulse-backend`). -2. Verify environment override: `systemctl show pulse --property=Environment`. -3. Docker: Ensure you updated the `-p` flag (e.g., `-p 8080:7655`). + +The web UI and API listen on `FRONTEND_PORT` (default `7655`). The deprecated +`PORT` alias applies only when `FRONTEND_PORT` is unset; changing +`frontendPort` in `system.json` has no effect. `PULSE_AGENT_INGEST_PORT` is a +separate agent listener, not the web UI port. See +[Port configuration](CONFIGURATION.md#common-overrides-environment-variables). + +- **Systemd / Proxmox LXC**: identify the active service with + `systemctl is-active pulse` (legacy installs may use `pulse-backend`). Inspect + only the port setting in its managed configuration locally. If you change a + unit or drop-in, run `sudo systemctl daemon-reload`, then restart the affected + service during a suitable maintenance window. For LXC, run these checks inside + the Pulse container, not on the Proxmox host. +- **Docker / Compose**: distinguish the published host port from the listener + inside the container. With the default listener, `8080:7655` exposes the UI on + host port `8080`; changing the host port does not require `FRONTEND_PORT`. + In the repository's Compose file, `PULSE_PORT` controls this host-side mapping. + Save the mapping in your existing Compose project and apply it with + `docker compose up -d pulse`, keeping the same image and mounted data volume. + Restarting an existing container does not apply a new port mapping. For other + container managers, use their recreate/redeploy action while preserving the + data mount; do not delete the volume. +- **Reverse proxy**: check its upstream port and the firewall separately. A + working agent connection on a split-port deployment does not prove that the + web UI is reachable. + +Do not post full service environments, `docker inspect` output or resolved +`docker compose config` output: they can include passwords and tokens. Share +only the relevant port numbers and a redacted error if help is needed. ### "Connection Refused" - Check if Pulse is running. diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.ts index 46376c4b24..172e0345b4 100644 --- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts +++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts @@ -149,6 +149,28 @@ describe('docsLinks', () => { expect(help).toContain('If installation never started Pulse'); }); + it('keeps port troubleshooting specific without exposing deployment credentials', () => { + const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8'); + const ports = troubleshooting.split("### Port change didn't take effect")[1].split('\n### ')[0]; + + expect(ports).toContain('CONFIGURATION.md#common-overrides-environment-variables'); + expect(ports).toContain('`PORT` alias applies only when `FRONTEND_PORT` is unset'); + expect(ports).toContain('`frontendPort` in `system.json` has no effect'); + expect(ports).toContain('separate agent listener, not the web UI port'); + expect(ports).toContain('`systemctl is-active pulse`'); + expect(ports).toContain('`sudo systemctl daemon-reload`'); + expect(ports).toContain('inside\n the Pulse container, not on the Proxmox host'); + expect(ports).toContain('`docker compose up -d pulse`'); + expect(ports).toContain('same image and mounted data volume'); + expect(ports).toContain('Restarting an existing container does not apply a new port mapping'); + expect(ports).toContain('do not delete the volume'); + expect(ports).toContain('Do not post full service environments'); + expect(ports).not.toContain('--property=Environment'); + expect(ports).not.toMatch( + /`(?:sudo )?(?:systemctl (?:status|cat)|docker inspect|docker compose config)[^`]*`(?! output)/, + ); + }); + it('keeps clone identity recovery separate from destructive OS or credential resets', () => { const troubleshooting = readFileSync(path.join(repoRoot, 'docs', 'TROUBLESHOOTING.md'), 'utf8'); const agentGuide = readFileSync(path.join(repoRoot, 'docs', 'UNIFIED_AGENT.md'), 'utf8');