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
Keep manual server installation help on the hardened path
pulse-triage[bot]a6959e571ba0
diff --git a/docs/INSTALL.md b/docs/INSTALL.mdindex 70e326c93e..0e7a9adb2d 100644--- a/docs/INSTALL.md+++ b/docs/INSTALL.md@@ -193,40 +193,43 @@ sudo bash install.sh --version "${PULSE_VERSION}"> **Note**: This installs the Pulse server. Use the `/install.sh` endpoint from **Settings → Infrastructure → Install on a host** for installing or upgrading `pulse-agent` on monitored hosts.<details>-<summary><strong>Manual systemd install (advanced)</strong></summary>+<summary><strong>Manual or custom systemd services (advanced)</strong></summary>++For a **new Pulse server**, use the signed installer above rather than copying+one binary and writing a minimal service unit. The installer creates the+`pulse` service account, prepares the release tree and data ownership, and+installs the server service and update assets together. Its server unit uses+`User=pulse`, `Group=pulse`, `NoNewPrivileges=true`, `PrivateTmp=true`,+`ProtectSystem=strict` and `ProtectHome=true`, with writes limited to the+installation and data directories. Pulse's server does not need a root service;+the separate host **agent** has different privilege requirements (see+[Agent Security](AGENT_SECURITY.md)).++For an **existing manual or custom installation**, first inspect its effective+service settings locally. This read-only command does not print environment+values or credentials:```bash-# Download and extract the architecture-specific tarball from GitHub Releases:-# https://github.com/rcourtman/Pulse/releases-# e.g.-# curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/pulse-${PULSE_VERSION}-linux-amd64.tar.gz"-# tar -xzf "pulse-${PULSE_VERSION}-linux-amd64.tar.gz"-# The extracted tree contains ./bin/pulse plus ./bin/pulse-agent-* and ./scripts/.--sudo install -m 0755 bin/pulse /usr/local/bin/pulse--# Create systemd service-sudo tee /etc/systemd/system/pulse.service > /dev/null << 'EOF'-[Unit]-Description=Pulse Monitoring-After=network.target--[Service]-Type=simple-ExecStart=/usr/local/bin/pulse-Restart=always-RestartSec=10-Environment=PULSE_DATA_DIR=/etc/pulse--[Install]-WantedBy=multi-user.target-EOF--# Start service-sudo mkdir -p /etc/pulse-sudo systemctl daemon-reload-sudo systemctl enable --now pulse+systemctl show pulse.service \+ --property=User --property=Group --property=NoNewPrivileges \+ --property=PrivateTmp --property=ProtectSystem --property=ProtectHome```++Use your actual server unit name if it differs; older installations may use+`pulse-backend.service`. An empty `User=` means systemd runs the service as+root. Missing hardening is not repaired just by downloading a new binary:+**the installer preserves existing service units during updates**, including+custom units.++Do not overwrite a working unit, change only its service user, or reinstall over+an existing data directory to match these settings. Before a migration, follow+[the recovery guide](RECOVERY.md), preserve the data directory and its encryption+key, and record the active data path and deployment-managed configuration+privately. Check that the intended service account can access that state and+that required integrations work with the chosen sandbox. Do not loosen data+permissions, remove authentication or share a full unit/environment dump as a+shortcut.+</details>---diff --git a/frontend-modern/browser-tests/docs-fragment-navigation.tsx b/frontend-modern/browser-tests/docs-fragment-navigation.tsxindex 2c125f2a3b..b7e8976db6 100644--- a/frontend-modern/browser-tests/docs-fragment-navigation.tsx+++ b/frontend-modern/browser-tests/docs-fragment-navigation.tsx@@ -23,6 +23,7 @@ const targets: Record<string, string> = {missing: '/docs/API#does-not-exist',troubleshooting: '/docs/TROUBLESHOOTING#recovery-mode',truenas: '/docs/TRUENAS',+ installation: '/docs/INSTALL',};window.history.replaceState({}, '', targets[scenario] ?? targets.plain);diff --git a/frontend-modern/browser-tests/systemd-install-help.cjs b/frontend-modern/browser-tests/systemd-install-help.cjsnew file mode 100644index 0000000000..bf9592a683--- /dev/null+++ b/frontend-modern/browser-tests/systemd-install-help.cjs@@ -0,0 +1,100 @@+// Exercise the real Docs renderer/router/styles and shipped installation guide.+// This is help verification, not an installed service migration or upgrade.+const assert = require('node:assert/strict');+const fs = require('node:fs');+const path = require('node:path');+const crypto = require('node:crypto');+const { chromium, webkit } = require('playwright');++(async () => {+ const root = '/workspace/frontend-modern';+ const artifacts = path.join(root, 'node_modules', 'systemd-install-help-browser');+ fs.mkdirSync(artifacts, { recursive: true });+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));+ const server = await createServer({+ root,+ configFile: path.join(root, 'vite.config.ts'),+ cacheDir: path.join(root, 'node_modules', '.vite-systemd-install-help'),+ server: { host: '127.0.0.1', port: 5251, strictPort: true },+ optimizeDeps: { noDiscovery: true, include: [] },+ });+ const results = [];+ let browser;+ try {+ await server.listen();+ for (const [engine, width] of [['chromium', 1280], ['webkit', 390]]) {+ browser = await { chromium, webkit }[engine].launch(engine === 'chromium'+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }+ : { headless: true });+ const page = await browser.newPage({ viewport: { width, height: 1000 },+ ...(engine === 'webkit' ? { isMobile: true, hasTouch: true } : {}) });+ const errors = [];+ page.on('pageerror', (error) => errors.push(error.message));+ page.on('console', (message) => {+ if (message.type() === 'error') errors.push(message.text());+ });+ await page.goto('http://127.0.0.1:5251/browser-tests/docs-fragment-navigation.html?scenario=installation',+ { waitUntil: 'domcontentloaded', timeout: 60_000 });+ const summary = page.locator('summary').filter({+ hasText: 'Manual or custom systemd services (advanced)',+ });+ await summary.waitFor();+ if (engine === 'webkit') {+ await page.evaluate(async () => {+ document.documentElement.classList.add('dark');+ await new Promise((resolve) => requestAnimationFrame(() => requestAnimationFrame(resolve)));+ await Promise.all(document.getAnimations().map((animation) => animation.finished.catch(() => {})));+ });+ }+ const details = summary.locator('..');+ assert.equal(await details.getAttribute('open'), null);+ await summary.focus();+ await page.keyboard.press('Enter');+ assert.notEqual(await details.getAttribute('open'), null);+ const content = await details.innerText();+ for (const text of ['use the signed installer above', 'User=pulse', 'Group=pulse',+ 'NoNewPrivileges=true', 'ProtectSystem=strict', 'An empty User= means',+ 'the installer preserves existing service units during updates',+ 'Do not overwrite a working unit, change only its service user',+ 'preserve the data directory and its encryption key',+ 'separate host agent has different privilege requirements'])+ assert.ok(content.includes(text), text);+ const command = await details.locator('pre').innerText();+ assert.ok(command.startsWith('systemctl show pulse.service'));+ assert.ok(!/--property=(Environment|ExecStart)|sudo|tee|install -m/.test(command));+ assert.ok(!await page.locator('article').innerText().then((text) =>+ text.includes('sudo tee /etc/systemd/system/pulse.service')));+ await summary.evaluate((element) => element.scrollIntoView({ block: 'start' }));+ await page.screenshot({ path: path.join(artifacts, `${engine}-account.png`) });+ await details.locator('pre').evaluate((element) => element.scrollIntoView({ block: 'start' }));+ await page.screenshot({ path: path.join(artifacts, `${engine}-checks.png`) });+ assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));+ const recovery = details.getByRole('link', { name: 'the recovery guide', exact: true });+ assert.equal(await recovery.getAttribute('href'), '/docs/RECOVERY');+ await recovery.focus();+ await page.keyboard.press('Enter');+ await page.waitForURL('**/docs/RECOVERY');+ await page.getByRole('heading', { level: 1 }).filter({ hasText: 'Recovery' }).waitFor();+ assert.deepEqual(errors, []);+ results.push({ engine, version: browser.version(), width,+ keyboardDisclosure: true, nonRootServer: true, agentBoundary: true,+ readOnlyCredentialSafeCommand: true, preservationWarning: true,+ noDocumentOverflow: true, keyboardRecoveryLink: true, errors });+ await browser.close();+ browser = undefined;+ }+ const files = ['public/docs/INSTALL.md', 'browser-tests/systemd-install-help.cjs',+ 'browser-tests/docs-fragment-navigation.tsx', 'src/features/docs/docMarkdown.ts',+ 'src/pages/Docs.tsx'].map((file) => ({ file,+ sha256: crypto.createHash('sha256').update(fs.readFileSync(path.join(root, file))).digest('hex') }));+ const result = { result: 'passed', playwright: require('playwright/package.json').version,+ scope: 'existing shipped installation-help rendering and navigation, not installed/systemd acceptance',+ dompurify: JSON.parse(fs.readFileSync(path.join(root, 'node_modules/dompurify/package.json'))).version,+ files, results };+ fs.writeFileSync(path.join(artifacts, 'result.json'), JSON.stringify(result, null, 2) + '\n');+ console.log(JSON.stringify(result));+ } finally {+ if (browser) await browser.close();+ await server.close();+ }+})().catch((error) => { console.error(error); process.exitCode = 1; });diff --git a/frontend-modern/public/docs/INSTALL.md b/frontend-modern/public/docs/INSTALL.mdindex 70e326c93e..0e7a9adb2d 100644--- a/frontend-modern/public/docs/INSTALL.md+++ b/frontend-modern/public/docs/INSTALL.md@@ -193,40 +193,43 @@ sudo bash install.sh --version "${PULSE_VERSION}"> **Note**: This installs the Pulse server. Use the `/install.sh` endpoint from **Settings → Infrastructure → Install on a host** for installing or upgrading `pulse-agent` on monitored hosts.<details>-<summary><strong>Manual systemd install (advanced)</strong></summary>+<summary><strong>Manual or custom systemd services (advanced)</strong></summary>++For a **new Pulse server**, use the signed installer above rather than copying+one binary and writing a minimal service unit. The installer creates the+`pulse` service account, prepares the release tree and data ownership, and+installs the server service and update assets together. Its server unit uses+`User=pulse`, `Group=pulse`, `NoNewPrivileges=true`, `PrivateTmp=true`,+`ProtectSystem=strict` and `ProtectHome=true`, with writes limited to the+installation and data directories. Pulse's server does not need a root service;+the separate host **agent** has different privilege requirements (see+[Agent Security](AGENT_SECURITY.md)).++For an **existing manual or custom installation**, first inspect its effective+service settings locally. This read-only command does not print environment+values or credentials:```bash-# Download and extract the architecture-specific tarball from GitHub Releases:-# https://github.com/rcourtman/Pulse/releases-# e.g.-# curl -fsSLO "https://github.com/rcourtman/Pulse/releases/download/${PULSE_VERSION}/pulse-${PULSE_VERSION}-linux-amd64.tar.gz"-# tar -xzf "pulse-${PULSE_VERSION}-linux-amd64.tar.gz"-# The extracted tree contains ./bin/pulse plus ./bin/pulse-agent-* and ./scripts/.--sudo install -m 0755 bin/pulse /usr/local/bin/pulse--# Create systemd service-sudo tee /etc/systemd/system/pulse.service > /dev/null << 'EOF'-[Unit]-Description=Pulse Monitoring-After=network.target--[Service]-Type=simple-ExecStart=/usr/local/bin/pulse-Restart=always-RestartSec=10-Environment=PULSE_DATA_DIR=/etc/pulse--[Install]-WantedBy=multi-user.target-EOF--# Start service-sudo mkdir -p /etc/pulse-sudo systemctl daemon-reload-sudo systemctl enable --now pulse+systemctl show pulse.service \+ --property=User --property=Group --property=NoNewPrivileges \+ --property=PrivateTmp --property=ProtectSystem --property=ProtectHome```++Use your actual server unit name if it differs; older installations may use+`pulse-backend.service`. An empty `User=` means systemd runs the service as+root. Missing hardening is not repaired just by downloading a new binary:+**the installer preserves existing service units during updates**, including+custom units.++Do not overwrite a working unit, change only its service user, or reinstall over+an existing data directory to match these settings. Before a migration, follow+[the recovery guide](RECOVERY.md), preserve the data directory and its encryption+key, and record the active data path and deployment-managed configuration+privately. Check that the intended service account can access that state and+that required integrations work with the chosen sandbox. Do not loosen data+permissions, remove authentication or share a full unit/environment dump as a+shortcut.+</details>---diff --git a/frontend-modern/src/utils/__tests__/docsLinks.test.ts b/frontend-modern/src/utils/__tests__/docsLinks.test.tsindex 69144e2f20..255b77334b 100644--- a/frontend-modern/src/utils/__tests__/docsLinks.test.ts+++ b/frontend-modern/src/utils/__tests__/docsLinks.test.ts@@ -61,6 +61,27 @@ function getRuntimeSourceFiles(dir: string): string[] {}describe('docsLinks', () => {+ it('keeps custom systemd server help on the signed non-root install path', () => {+ const installation = readFileSync(path.join(repoRoot, 'docs', 'INSTALL.md'), 'utf8');+ const custom = installation+ .split('<summary><strong>Manual or custom systemd services (advanced)</strong></summary>')[1]+ .split('</details>')[0];+ expect(custom).toContain('use the signed installer above');+ expect(custom).toContain('`User=pulse`, `Group=pulse`');+ expect(custom).toContain('`ProtectSystem=strict` and `ProtectHome=true`');+ expect(custom).toContain('An empty `User=` means');+ expect(custom).toContain('the installer preserves existing service units during updates');+ expect(custom).toContain('Do not overwrite a working unit, change only its service user');+ expect(custom).toContain('preserve the data directory and its encryption');+ expect(custom).toContain('separate host **agent** has different privilege requirements');+ const commands = [...custom.matchAll(/```bash\n([\s\S]*?)```/g)].map((match) => match[1]);+ expect(commands).toHaveLength(1);+ expect(commands[0]).toContain('systemctl show pulse.service');+ expect(commands[0]).not.toMatch(/--property=(Environment|ExecStart)|sudo|tee|install -m/);+ expect(installation).not.toContain('sudo tee /etc/systemd/system/pulse.service');+ expect(installation).not.toContain('ExecStart=/usr/local/bin/pulse');+ });+it('keeps TrueNAS setup acceptance separate from a system-information probe', () => {const truenas = readFileSync(path.join(repoRoot, 'docs', 'TRUENAS.md'), 'utf8');const setup = truenas.split('## Quick Start')[1].split('## Creating a TrueNAS API Key')[0];