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.

Separate installation completion from a usable Pulse server

pulse-triage[bot]65990fc47ad7
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 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 Setup
Pulse 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.md
index 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 configuration
or 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 a
monitored container is a different job; use
diff --git a/frontend-modern/public/docs/INSTALL.md b/frontend-modern/public/docs/INSTALL.md
index 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 Setup
Pulse 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.md
index 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 configuration
or 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 a
monitored container is a different job; use
diff --git a/frontend-modern/src/features/docs/__tests__/installationStartupGuide.test.ts b/frontend-modern/src/features/docs/__tests__/installationStartupGuide.test.ts
new file mode 100644
index 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`));
+ }
+ });
+});