gsadmin/pulse
1
0
Fork 0
mirror of https://github.com/rcourtman/Pulse.git synced 2026-10-23 20:25:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

Make port troubleshooting safe and deployment-specific

Browse Source 
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
This commit is contained in:
pulse-triage[bot]
2026-09-30 08:17:43 +01:00
parent 5cc1f2f7b0
commit 9bc6f6ed64
3 changed files with 80 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/TROUBLESHOOTING.md
+29 -3
View File
@@ -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.
frontend-modern/public/docs/TROUBLESHOOTING.md
+29 -3
View File
@@ -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.
frontend-modern/src/utils/__tests__/docsLinks.test.ts
+22
View File
@@ -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');