Skip to content

armgit / Pulse

Public Imported from GitHub
0

Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.

Explain why green health can accompany a stalled dashboard

pulse-triage[bot]da25a6e88c44
diff --git a/docs/API.md b/docs/API.md
index def600fa83..eda7cd1492 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -207,17 +207,38 @@ reports, accept tokens bound to that organization with the listed scope.
## 📡 Core Endpoints
### System Health
-`GET /api/health`
-Check if Pulse is running.
+`GET /api/health` (also accepts `HEAD`)
+
+Public server liveness response: `200` for the handler's healthy condition,
+`503` for its unhealthy condition. A GET response can include:
+
```json
{
"status": "healthy",
"timestamp": 1700000000,
"uptime": 3600,
- "devModeSSH": false
+ "devModeSSH": false,
+ "dependencies": {
+ "monitor": true,
+ "scheduler": true,
+ "websocket": true
+ }
}
```
+**Liveness is not end-to-end readiness.** A `200`, `"status": "healthy"`, or
+true dependency flags do not establish successful authentication, current
+polling, delivery of dashboard state over `/ws`, or notification delivery.
+In particular, `websocket: true` is not proof that a browser received its
+initial state; a successful WebSocket upgrade or welcome message is not that
+proof either. A container health badge based only on this endpoint inherits
+these limits.
+
+If health is green while the dashboard is stuck or stale, use the
+[stalled-dashboard guidance](TROUBLESHOOTING.md#health-is-green-but-the-dashboard-is-stalled).
+Do not add repeated state requests or an automatic restart loop to turn this
+limited check into a readiness test; preserve the original failure evidence.
+
### System State
`GET /api/state`
Returns the complete state of your infrastructure (Nodes, VMs, Containers, Storage, Alerts). This is the main endpoint used by the dashboard.
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index a45d665af2..c8903393a1 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -14,6 +14,9 @@ establish safe recovery.
- **Not sure which version is affected:** distinguish the
[running server, reported agent and update target](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions).
A helper's selected release or an agent's target is not its running version.
+- **Dashboard is stuck on “Connecting to Pulse” or stops updating:** distinguish
+ [server liveness from dashboard delivery](#health-is-green-but-the-dashboard-is-stalled).
+ Green health is not proof that current readings reached your browser.
- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)
or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),
according to the existing authentication method. Do not delete configuration
@@ -276,6 +279,36 @@ do not replace credentials or disable TLS verification on a refusal alone.
For a page that opens but has missing readings, use the
[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.
+### Health is green but the dashboard is stalled
+
+A public [`/api/health` response](API.md#system-health) checks limited server
+liveness, not end-to-end readiness. HTTP `200`, `"status": "healthy"` or a
+container's **healthy** badge can coexist with “Connecting to Pulse”, no initial
+state or stale readings. They do not verify sign-in, recent platform polling,
+dashboard-state delivery or notification delivery.
+
+Use observations from the original failure, not a new diagnostic run:
+
+| Existing observation | What it establishes — and what it does not |
+| --- | --- |
+| Pulse's page does not open | Check the [installation and service distinction](INSTALL.md#installation-did-not-reach-a-usable-server) and [connection path](#connection-refused). A healthy response from another address, proxy or earlier time does not establish this page's availability. |
+| Sign-in succeeds and the page stays on “Connecting to Pulse” | Authentication worked for that attempt; the dashboard still did not become usable. A successful `/ws` upgrade or welcome message opens the transport, but does not establish receipt of initial state. It does not identify a lock owner or prove a proxy, browser-cache or credential fault. |
+| The dashboard opens but readings stop advancing | Compare the affected resource's last visible observation with the original incident time. An open connection does not prove that collection or delivery continues; a current value, a retained value and stored History are separate evidence. Follow the [missing-data checks](FAQ.md#no-data-showing) for the affected source. |
+
+Keep the failure time and timezone, running server version and exact displayed
+message when already available. If you already have browser network evidence,
+retain only the relevant request path, status and timing or redacted error.
+Keep cookies, headers, query values, WebSocket frames, full responses and network
+exports private; do not use **Copy as cURL**. An unavailable observation is
+unknown, not success or an empty infrastructure list.
+
+Do not restart, reinstall, clear browser storage, sign out, bypass the proxy,
+disable TLS or run Diagnostics just to demonstrate recovery. Do not send
+repeated state requests, induce a freeze or take a process-terminating dump to
+recreate the incident. Preserve existing configuration, credentials and logs;
+[report the evidence already available](#-getting-help). A later recovery does
+not explain the earlier failure, and this guidance is not a runtime fix.
+
### Proxmox or PBS certificate validation failed
A TLS error is not an invalid API token or a missing permission. Keep the
diff --git a/frontend-modern/public/docs/API.md b/frontend-modern/public/docs/API.md
index def600fa83..eda7cd1492 100644
--- a/frontend-modern/public/docs/API.md
+++ b/frontend-modern/public/docs/API.md
@@ -207,17 +207,38 @@ reports, accept tokens bound to that organization with the listed scope.
## 📡 Core Endpoints
### System Health
-`GET /api/health`
-Check if Pulse is running.
+`GET /api/health` (also accepts `HEAD`)
+
+Public server liveness response: `200` for the handler's healthy condition,
+`503` for its unhealthy condition. A GET response can include:
+
```json
{
"status": "healthy",
"timestamp": 1700000000,
"uptime": 3600,
- "devModeSSH": false
+ "devModeSSH": false,
+ "dependencies": {
+ "monitor": true,
+ "scheduler": true,
+ "websocket": true
+ }
}
```
+**Liveness is not end-to-end readiness.** A `200`, `"status": "healthy"`, or
+true dependency flags do not establish successful authentication, current
+polling, delivery of dashboard state over `/ws`, or notification delivery.
+In particular, `websocket: true` is not proof that a browser received its
+initial state; a successful WebSocket upgrade or welcome message is not that
+proof either. A container health badge based only on this endpoint inherits
+these limits.
+
+If health is green while the dashboard is stuck or stale, use the
+[stalled-dashboard guidance](TROUBLESHOOTING.md#health-is-green-but-the-dashboard-is-stalled).
+Do not add repeated state requests or an automatic restart loop to turn this
+limited check into a readiness test; preserve the original failure evidence.
+
### System State
`GET /api/state`
Returns the complete state of your infrastructure (Nodes, VMs, Containers, Storage, Alerts). This is the main endpoint used by the dashboard.
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index a45d665af2..c8903393a1 100644
--- a/frontend-modern/public/docs/TROUBLESHOOTING.md
+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md
@@ -14,6 +14,9 @@ establish safe recovery.
- **Not sure which version is affected:** distinguish the
[running server, reported agent and update target](TROUBLESHOOTING.md#find-the-running-server-and-agent-versions).
A helper's selected release or an agent's target is not its running version.
+- **Dashboard is stuck on “Connecting to Pulse” or stops updating:** distinguish
+ [server liveness from dashboard delivery](#health-is-green-but-the-dashboard-is-stalled).
+ Green health is not proof that current readings reached your browser.
- **Cannot sign in:** use [local password recovery](TROUBLESHOOTING.md#i-forgot-my-password)
or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),
according to the existing authentication method. Do not delete configuration
@@ -276,6 +279,36 @@ do not replace credentials or disable TLS verification on a refusal alone.
For a page that opens but has missing readings, use the
[missing-data checks](FAQ.md#no-data-showing) instead of resetting the connection.
+### Health is green but the dashboard is stalled
+
+A public [`/api/health` response](API.md#system-health) checks limited server
+liveness, not end-to-end readiness. HTTP `200`, `"status": "healthy"` or a
+container's **healthy** badge can coexist with “Connecting to Pulse”, no initial
+state or stale readings. They do not verify sign-in, recent platform polling,
+dashboard-state delivery or notification delivery.
+
+Use observations from the original failure, not a new diagnostic run:
+
+| Existing observation | What it establishes — and what it does not |
+| --- | --- |
+| Pulse's page does not open | Check the [installation and service distinction](INSTALL.md#installation-did-not-reach-a-usable-server) and [connection path](#connection-refused). A healthy response from another address, proxy or earlier time does not establish this page's availability. |
+| Sign-in succeeds and the page stays on “Connecting to Pulse” | Authentication worked for that attempt; the dashboard still did not become usable. A successful `/ws` upgrade or welcome message opens the transport, but does not establish receipt of initial state. It does not identify a lock owner or prove a proxy, browser-cache or credential fault. |
+| The dashboard opens but readings stop advancing | Compare the affected resource's last visible observation with the original incident time. An open connection does not prove that collection or delivery continues; a current value, a retained value and stored History are separate evidence. Follow the [missing-data checks](FAQ.md#no-data-showing) for the affected source. |
+
+Keep the failure time and timezone, running server version and exact displayed
+message when already available. If you already have browser network evidence,
+retain only the relevant request path, status and timing or redacted error.
+Keep cookies, headers, query values, WebSocket frames, full responses and network
+exports private; do not use **Copy as cURL**. An unavailable observation is
+unknown, not success or an empty infrastructure list.
+
+Do not restart, reinstall, clear browser storage, sign out, bypass the proxy,
+disable TLS or run Diagnostics just to demonstrate recovery. Do not send
+repeated state requests, induce a freeze or take a process-terminating dump to
+recreate the incident. Preserve existing configuration, credentials and logs;
+[report the evidence already available](#-getting-help). A later recovery does
+not explain the earlier failure, and this guidance is not a runtime fix.
+
### Proxmox or PBS certificate validation failed
A TLS error is not an invalid API token or a missing permission. Keep the
diff --git a/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.ts b/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.ts
new file mode 100644
index 0000000000..d86f22e5e8
--- /dev/null
+++ b/frontend-modern/src/features/docs/__tests__/dashboardReadinessGuide.test.ts
@@ -0,0 +1,84 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '../docMarkdown';
+
+const read = (file: string) => readFileSync(path.resolve(process.cwd(), '..', file), 'utf8');
+const anchor = 'health-is-green-but-the-dashboard-is-stalled';
+const guide = (name: string) => read(`docs/${name}.md`);
+const article = (markdown: string, name: string) => {
+ const element = document.createElement('article');
+ element.innerHTML = renderDocMarkdown(markdown, name);
+ return element;
+};
+// Render the real section, not an invented diagnostic page or source-code spelling.
+const section = (name: string, heading: string) => {
+ const markdown = guide(name).split(`### ${heading}\n`)[1]?.split('\n### ')[0];
+ expect(markdown, heading).toBeDefined();
+ return article(`### ${heading}\n${markdown}`, name);
+};
+const text = (node: HTMLElement) => node.textContent!.replace(/\s+/g, ' ').trim();
+const stalled = () => section('TROUBLESHOOTING', 'Health is green but the dashboard is stalled');
+
+describe('dashboard readiness guidance', () => {
+ it('offers a real symptom entry and working two-way API links', () => {
+ const entry = guide('TROUBLESHOOTING').split('\n## ⚡ Quick Fixes')[0];
+ const rendered = article(entry, 'TROUBLESHOOTING');
+ const links = rendered.querySelectorAll(`a[href="#${anchor}"]`);
+ expect(links).toHaveLength(1);
+ expect(text(links[0].closest('li')!)).toMatch(/Connecting to Pulse.*stops updating/);
+ expect(stalled().querySelector(`#${anchor}`)?.tagName).toBe('H3');
+ expect(stalled().querySelector('a[href="/docs/API#system-health"]')).not.toBeNull();
+ const health = section('API', 'System Health');
+ expect(health.querySelector('#system-health')?.tagName).toBe('H3');
+ expect(health.querySelector(`a[href="/docs/TROUBLESHOOTING#${anchor}"]`)).not.toBeNull();
+ });
+
+ it('separates public liveness and dependency presence from usable dashboard delivery', () => {
+ const health = section('API', 'System Health');
+ const copy = text(health);
+ expect(copy).toMatch(/GET \/api\/health.*HEAD/);
+ expect(copy).toMatch(/Public.*200.*503/);
+ expect(copy).toMatch(/Liveness is not end-to-end readiness/);
+ expect(copy).toMatch(/do not establish.*authentication.*polling.*dashboard state.*notification/);
+ expect(copy).toMatch(/websocket: true is not proof.*initial state/);
+ expect(copy).toMatch(/upgrade or welcome message is not that proof/);
+ expect(copy).toMatch(/container health badge.*inherits these limits/);
+ const example = JSON.parse(health.querySelector('pre code')!.textContent!);
+ expect(example.dependencies).toEqual({ monitor: true, scheduler: true, websocket: true });
+ expect(example.status).toBe('healthy');
+ });
+
+ it('keeps connection, authentication, initial state and advancing readings distinct', () => {
+ const rendered = stalled();
+ const rows = [...rendered.querySelectorAll('tbody tr')];
+ expect(rows).toHaveLength(3);
+ expect(text(rows[0])).toMatch(/page does not open.*another address, proxy or earlier time/);
+ expect(text(rows[1])).toMatch(/Sign-in succeeds.*Authentication worked.*does not establish receipt of initial state/);
+ expect(text(rows[1])).toMatch(/does not identify a lock owner.*proxy, browser-cache or credential fault/);
+ expect(text(rows[2])).toMatch(/readings stop advancing.*collection or delivery continues/);
+ expect(text(rows[2])).toMatch(/current value.*retained value.*stored History/);
+ expect(rendered.querySelector('a[href="/docs/FAQ#no-data-showing"]')).not.toBeNull();
+ expect(rendered.querySelector('a[href="/docs/INSTALL#installation-did-not-reach-a-usable-server"]')).not.toBeNull();
+ expect(rendered.querySelector('a[href="#connection-refused"]')).not.toBeNull();
+ });
+
+ it('uses existing evidence without extra probes, reset advice or credential-bearing exports', () => {
+ const rendered = stalled();
+ const copy = text(rendered);
+ expect(rendered.querySelector('pre')).toBeNull();
+ expect(copy).toMatch(/original failure, not a new diagnostic run/);
+ expect(copy).toMatch(/when already available/);
+ expect(copy).toMatch(/cookies, headers, query values, WebSocket frames, full responses.*exports private/);
+ expect(copy).toMatch(/do not use Copy as cURL/);
+ expect(copy).toMatch(/unavailable observation is unknown, not success/);
+ expect(copy).toMatch(/Do not restart, reinstall, clear browser storage, sign out, bypass the proxy, disable TLS or run Diagnostics/);
+ expect(copy).toMatch(/Do not send repeated state requests, induce a freeze or take a process-terminating dump/);
+ expect(copy).toMatch(/Preserve existing configuration, credentials and logs/);
+ expect(copy).toMatch(/guidance is not a runtime fix/);
+ expect(rendered.querySelector('a[href="#-getting-help"]')).not.toBeNull();
+ for (const name of ['API', 'TROUBLESHOOTING']) {
+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(guide(name));
+ }
+ });
+});
diff --git a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts
index e4ef20bbad..8b94565ff9 100644
--- a/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts
+++ b/frontend-modern/src/features/docs/__tests__/troubleshootingEntryGuide.test.ts
@@ -90,6 +90,10 @@ describe('troubleshooting workflow entry', () => {
'Unraid reports missing disks in empty slots:',
['/docs/TROUBLESHOOTING#unraid-reports-missing-disks-in-empty-slots'],
],
+ [
+ 'Dashboard is stuck on “Connecting to Pulse” or stops updating:',
+ ['#health-is-green-but-the-dashboard-is-stalled'],
+ ],
[
'Cannot sign in:',
[