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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Separate installation completion from a usable Pulse server
pulse-triage[bot]65990fc47ad7
diff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 5084bcf62a..34e0d411ae 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -69,7 +69,8 @@ must not add other URLs, disable TLS verification or change these transfers.Both downloads and the signature check must succeed before the installer runs.A verified signature proves authenticity, not successful installation or recovery.If the installer itself fails or its outcome is uncertain, inspect the existing-service/container and [recovery instructions](RECOVERY.md) before another attempt.+service/container using [startup checks](#installation-did-not-reach-a-usable-server)+and the [recovery instructions](RECOVERY.md) before another attempt.### Proxmox VE (LXC installer)If you run Proxmox VE, the easiest and most “Pulse-native” deployment is the official installer which creates and configures a lightweight LXC container.@@ -264,6 +265,54 @@ shortcut.---+## Installation did not reach a usable server++An installer banner, a zero exit status or a verified download is not proof of+a usable Pulse server. Keep the original result and time; do not rerun the+installer, restart the host or repeat first-time setup just to obtain evidence.++For **systemd or Proxmox LXC server installs**, separate these observations:++1. **Container or host state.** A running LXC does not establish that Pulse is+ running inside it. If the LXC is stopped or its state is uncertain, retain+ that fact; do not boot it merely to run the check below. A whole-container+ stop is different from a stopped Pulse service.+2. **Pulse service state.** In the affected server's existing shell or console+ (inside the Pulse LXC, not on its Proxmox host), this bounded read shows only+ selected service-state properties, not environment values or log content:++ ```bash+ timeout -k 1 5 systemctl show pulse.service --no-pager \+ --property=LoadState --property=ActiveState --property=SubState --property=Result+ ```++ Use the actual server unit name recorded by your installation if it differs;+ do not substitute `pulse-agent.service`. `LoadState=not-found` can mean a+ wrong unit name or incomplete service installation. An error, timeout or+ missing property is an **unavailable read**, not evidence of an inactive or+ healthy service. `ActiveState=active` describes this observation only; it+ does not establish application readiness or explain an earlier stop.+3. **Web access.** Open the existing Pulse address in your browser. A reachable+ login/setup page, successful sign-in and current monitoring are separate+ observations; an active service alone does not establish them. Do not remove+ authentication or change firewall/TLS settings merely to make a check pass.++For **Docker, Compose or Kubernetes**, inspect the existing deployment's state+and image reference in its manager instead; the systemd command above is not a+container-health check. Do not recreate containers, remove volumes or change+images just to diagnose startup.++Keep configuration, encryption keys, persistent data and rollback copies intact.+If the service cannot be confirmed running, use the existing+[bounded local log reader](TROUBLESHOOTING.md#inspect-notification-logs) where+safe, then the [state-preserving recovery guidance](RECOVERY.md). Keep full+journals and service/environment dumps private. A report can use the original+error, relevant state properties, attempted version and recovery already+performed; unknowns are valid, and another install attempt is not required.+Continue below only for a genuinely new installation with a reachable setup+page; an existing installation's login belongs to+[login recovery](TROUBLESHOOTING.md#i-forgot-my-password), not new setup.+## 🔐 First-Time SetupPulse is secure by default. On first launch, you must retrieve a **Bootstrap Token** to create your admin account.diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 3439a3109b..a45d665af2 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -18,6 +18,9 @@ establish safe recovery.or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),according to the existing authentication method. Do not delete configurationor repeat first-time setup.+- **Server installation finished but Pulse is unavailable:** distinguish+ [container state, Pulse service state and web access](INSTALL.md#installation-did-not-reach-a-usable-server).+ Preserve the existing installation; a success banner is not readiness.- **Update failed or its result is uncertain:** start with[Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of amonitored container is a different job; usediff --git a/frontend-modern/public/docs/INSTALL.md b/frontend-modern/public/docs/INSTALL.mdindex 5084bcf62a..34e0d411ae 100644--- a/frontend-modern/public/docs/INSTALL.md+++ b/frontend-modern/public/docs/INSTALL.md@@ -69,7 +69,8 @@ must not add other URLs, disable TLS verification or change these transfers.Both downloads and the signature check must succeed before the installer runs.A verified signature proves authenticity, not successful installation or recovery.If the installer itself fails or its outcome is uncertain, inspect the existing-service/container and [recovery instructions](RECOVERY.md) before another attempt.+service/container using [startup checks](#installation-did-not-reach-a-usable-server)+and the [recovery instructions](RECOVERY.md) before another attempt.### Proxmox VE (LXC installer)If you run Proxmox VE, the easiest and most “Pulse-native” deployment is the official installer which creates and configures a lightweight LXC container.@@ -264,6 +265,54 @@ shortcut.---+## Installation did not reach a usable server++An installer banner, a zero exit status or a verified download is not proof of+a usable Pulse server. Keep the original result and time; do not rerun the+installer, restart the host or repeat first-time setup just to obtain evidence.++For **systemd or Proxmox LXC server installs**, separate these observations:++1. **Container or host state.** A running LXC does not establish that Pulse is+ running inside it. If the LXC is stopped or its state is uncertain, retain+ that fact; do not boot it merely to run the check below. A whole-container+ stop is different from a stopped Pulse service.+2. **Pulse service state.** In the affected server's existing shell or console+ (inside the Pulse LXC, not on its Proxmox host), this bounded read shows only+ selected service-state properties, not environment values or log content:++ ```bash+ timeout -k 1 5 systemctl show pulse.service --no-pager \+ --property=LoadState --property=ActiveState --property=SubState --property=Result+ ```++ Use the actual server unit name recorded by your installation if it differs;+ do not substitute `pulse-agent.service`. `LoadState=not-found` can mean a+ wrong unit name or incomplete service installation. An error, timeout or+ missing property is an **unavailable read**, not evidence of an inactive or+ healthy service. `ActiveState=active` describes this observation only; it+ does not establish application readiness or explain an earlier stop.+3. **Web access.** Open the existing Pulse address in your browser. A reachable+ login/setup page, successful sign-in and current monitoring are separate+ observations; an active service alone does not establish them. Do not remove+ authentication or change firewall/TLS settings merely to make a check pass.++For **Docker, Compose or Kubernetes**, inspect the existing deployment's state+and image reference in its manager instead; the systemd command above is not a+container-health check. Do not recreate containers, remove volumes or change+images just to diagnose startup.++Keep configuration, encryption keys, persistent data and rollback copies intact.+If the service cannot be confirmed running, use the existing+[bounded local log reader](TROUBLESHOOTING.md#inspect-notification-logs) where+safe, then the [state-preserving recovery guidance](RECOVERY.md). Keep full+journals and service/environment dumps private. A report can use the original+error, relevant state properties, attempted version and recovery already+performed; unknowns are valid, and another install attempt is not required.+Continue below only for a genuinely new installation with a reachable setup+page; an existing installation's login belongs to+[login recovery](TROUBLESHOOTING.md#i-forgot-my-password), not new setup.+## 🔐 First-Time SetupPulse is secure by default. On first launch, you must retrieve a **Bootstrap Token** to create your admin account.diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 3439a3109b..a45d665af2 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -18,6 +18,9 @@ establish safe recovery.or [401 and login failures](TROUBLESHOOTING.md#cannot-login--401-unauthorized),according to the existing authentication method. Do not delete configurationor repeat first-time setup.+- **Server installation finished but Pulse is unavailable:** distinguish+ [container state, Pulse service state and web access](INSTALL.md#installation-did-not-reach-a-usable-server).+ Preserve the existing installation; a success banner is not readiness.- **Update failed or its result is uncertain:** start with[Pulse server update checks](AUTO_UPDATE.md#update-failed). An update of amonitored container is a different job; usediff --git a/frontend-modern/src/features/docs/__tests__/installationStartupGuide.test.ts b/frontend-modern/src/features/docs/__tests__/installationStartupGuide.test.tsnew file mode 100644index 0000000000..b19ce5cb4a--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/installationStartupGuide.test.ts@@ -0,0 +1,107 @@+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 article = (name: string) => {+ const result = document.createElement('article');+ result.innerHTML = renderDocMarkdown(read(`docs/${name}.md`), name);+ return result;+};+const anchor = 'installation-did-not-reach-a-usable-server';+const section = () => {+ const heading = article('INSTALL').querySelector(`#${anchor}`);+ expect(heading?.tagName).toBe('H2');+ const result = document.createElement('section');+ for (+ let node = heading!.nextElementSibling;+ node && node.tagName !== 'H2';+ node = node.nextElementSibling+ ) {+ result.appendChild(node.cloneNode(true));+ }+ return result;+};+const prose = (element: HTMLElement) => element.textContent!.replace(/\s+/g, ' ').trim();++describe('installation startup guidance', () => {+ it('reaches the startup distinction before setup, from both existing entry paths', () => {+ const install = article('INSTALL');+ const heading = install.querySelector(`#${anchor}`)!;+ const entry = install.querySelector(`a[href="#${anchor}"]`)!;+ expect(entry).not.toBeNull();+ expect(entry.compareDocumentPosition(heading) & Node.DOCUMENT_POSITION_FOLLOWING).toBeTruthy();+ // Inspect heading order rather than relying on the emoji slug spelling.+ expect([...install.querySelectorAll('h2')].findIndex((node) => node === heading)).toBeLessThan(+ [...install.querySelectorAll('h2')].findIndex((node) =>+ node.textContent!.includes('First-Time Setup'),+ ),+ );+ expect(+ article('TROUBLESHOOTING').querySelector(`a[href="/docs/INSTALL#${anchor}"]`),+ ).not.toBeNull();+ });++ it('offers only a bounded property read, in the affected server rather than the hypervisor', () => {+ const rendered = section();+ const code = rendered.querySelectorAll('pre code');+ expect(code).toHaveLength(1);+ expect(+ code[0]+ .textContent!.replace(/\\\n\s*/g, ' ')+ .trim()+ .split(/\s+/),+ ).toEqual([+ 'timeout',+ '-k',+ '1',+ '5',+ 'systemctl',+ 'show',+ 'pulse.service',+ '--no-pager',+ '--property=LoadState',+ '--property=ActiveState',+ '--property=SubState',+ '--property=Result',+ ]);+ expect(prose(rendered)).toContain('inside the Pulse LXC, not on its Proxmox host');+ expect(prose(rendered)).toContain('do not substitute pulse-agent.service');+ expect(prose(rendered)).toContain('not a container-health check');+ expect(prose(rendered)).toContain('not environment values or log content');+ });++ it('does not confuse active, unavailable and ready or prescribe a second disruptive attempt', () => {+ const copy = prose(section());+ for (const distinction of [+ 'A running LXC does not establish that Pulse is running inside it',+ 'do not boot it merely to run the check',+ 'a wrong unit name or incomplete service installation',+ 'an unavailable read, not evidence of an inactive or healthy service',+ 'does not establish application readiness or explain an earlier stop',+ 'successful sign-in and current monitoring are separate observations',+ 'Do not remove authentication or change firewall/TLS settings',+ 'Do not recreate containers, remove volumes or change images',+ 'Keep configuration, encryption keys, persistent data and rollback copies intact',+ 'unknowns are valid',+ 'another install attempt is not required',+ ])+ expect(copy).toContain(distinction);+ });++ it('links to real recovery and private log guidance and keeps shipped guides identical', () => {+ for (const [name, fragment] of [+ ['TROUBLESHOOTING', 'inspect-notification-logs'],+ ['TROUBLESHOOTING', 'i-forgot-my-password'],+ ['RECOVERY', ''],+ ]) {+ const href = `/docs/${name}${fragment ? `#${fragment}` : ''}`;+ expect(section().querySelector(`a[href="${href}"]`)).not.toBeNull();+ if (fragment) expect(article(name).querySelector(`#${fragment}`)).not.toBeNull();+ }+ for (const name of ['INSTALL', 'TROUBLESHOOTING']) {+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(read(`docs/${name}.md`));+ }+ });+});