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
Preserve existing deployments in FAQ configuration help
pulse-triage[bot]5b72730caf8f
diff --git a/docs/FAQ.md b/docs/FAQ.mdindex ad35e2b307..d057a40391 100644--- a/docs/FAQ.md+++ b/docs/FAQ.md@@ -21,8 +21,27 @@ run the unified agent directly.If you want Pulse to find servers automatically, enable discovery in **Settings → System → Network** and then review discovered servers in **Settings → Infrastructure**.### How do I change the port?-- **Systemd**: `sudo systemctl edit pulse`, add `Environment="FRONTEND_PORT=8080"`, restart.-- **Docker**: Use `-p 8080:7655` in your run command.++Distinguish Pulse's web listener from a container's published host port.+`FRONTEND_PORT` controls the listener (default **7655**); the separate+`PULSE_AGENT_INGEST_PORT` is not the web UI port.++- **Systemd / Proxmox LXC**: change the active Pulse service's managed port+ setting. For LXC, work inside the Pulse container, not on the Proxmox host.+ A unit or drop-in change needs a service-manager reload and a restart of that+ service during a suitable maintenance window.+- **Docker / Compose**: with the default listener, `8080:7655` publishes the UI+ on host port **8080**; it does not require changing `FRONTEND_PORT`. The+ repository's Compose file uses `PULSE_PORT` for this host-side mapping.+ Apply the change through your existing container manager's recreate/redeploy+ operation, preserving the same image, data mount and other settings.+ `docker restart` does not apply a new port mapping. Do not delete a data volume+ or replace your existing deployment with a fresh `docker run` command.++Update the reverse proxy's upstream port separately if needed; do not expose+Pulse directly or broadly open the firewall to bypass it. Follow the+[deployment-specific port checks](TROUBLESHOOTING.md#port-change-didnt-take-effect)+and keep full service environments and container inspections private.### Does updating the Pulse server update every agent immediately?@@ -38,7 +57,28 @@ update. Use **Settings → Infrastructure → Install on a host** for first instand v5-to-v6 upgrades. See [Unified Agent](UNIFIED_AGENT.md#auto-update).### Why can't I change settings in the UI?-If a setting is disabled with an amber warning, it's being overridden by an environment variable (e.g., `DISCOVERY_ENABLED`). Remove the env var to regain UI control.++A warning that names an environment variable means that deployment setting+manages the value, rather than the UI. If it is intentional, keep it and ask+the deployment administrator to change that setting; do not remove unrelated+authentication or security overrides.++To hand that particular setting back to the UI, remove only its override from+the active deployment source. Apply through the same deployment: environment+changes for Docker require recreation/redeployment, not `docker restart`; a+systemd unit or drop-in change needs a service-manager reload and restart.+Preserve the image, data mount, credentials and other settings. Merely editing+a file does not change the running process's environment.++Re-open Settings afterwards and check both the warning and effective value.+Removing an override does not necessarily erase the saved value underneath it+or turn the setting off. For example, a saved CORS allowlist can remain after+`ALLOWED_ORIGINS` is removed. See+[environment precedence](CONFIGURATION.md#common-overrides-environment-variables) and+[CORS checks](TROUBLESHOOTING.md#cors-errors). If no environment warning is+shown, retain the displayed error rather than assuming an override is the cause.+Do not post full environment, Compose or configuration dumps; they can contain+passwords and tokens.---diff --git a/frontend-modern/browser-tests/faq-deployment-help.cjs b/frontend-modern/browser-tests/faq-deployment-help.cjsnew file mode 100644index 0000000000..2988c40108--- /dev/null+++ b/frontend-modern/browser-tests/faq-deployment-help.cjs@@ -0,0 +1,106 @@+// Verify shipped FAQ answers and their recovery links in the real Docs page.+// parent.md is the exact own-parent FAQ supplied locally before this run.+// No settings write, service/container change or external request is exercised.+const assert = require('node:assert/strict');+const fs = require('node:fs');+const path = require('node:path');+const { createHash } = require('node:crypto');+const { chromium, webkit } = require('playwright');++(async () => {+ const root = path.resolve('frontend-modern');+ const artifacts = path.join(root, 'node_modules/faq-deployment-browser');+ const parent = fs.readFileSync(path.join(artifacts, 'parent.md'), 'utf8');+ const final = fs.readFileSync(path.join(root, 'public/docs/FAQ.md'), 'utf8');+ const digest = (text) => createHash('sha256').update(text).digest('hex');+ process.chdir(root);+ 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(artifacts, 'vite-cache'),+ server: { host: '127.0.0.1', port: 5259, strictPort: true },+ optimizeDeps: { noDiscovery: true, include: [] },+ });+ const results = [];+ let browser;+ try {+ await server.listen();+ for (const [engine, width, tone] of [['chromium', 1280, 'light'], ['webkit', 390, 'dark']]) {+ browser = await { chromium, webkit }[engine].launch(engine === 'chromium'+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }+ : { headless: true });+ const context = await browser.newContext({ viewport: { width, height: 1000 },+ ...(engine === 'webkit' ? { isMobile: true, hasTouch: true } : {}) });+ const captures = [];+ for (const [label, content] of [['parent', parent], ['final', final]]) {+ const page = await context.newPage();+ const errors = [];+ page.on('pageerror', (error) => errors.push(error.message));+ await page.route('**/docs/FAQ.md', (route) => route.fulfill({+ status: 200, contentType: 'text/markdown; charset=utf-8', body: content,+ }));+ await page.goto('http://127.0.0.1:5259/browser-tests/docs-fragment-navigation.html',+ { waitUntil: 'domcontentloaded', timeout: 30_000 });+ if (tone === 'dark') await page.evaluate(() => document.documentElement.classList.add('dark'));+ await page.getByRole('link', { name: '← All documentation' }).click();+ const entry = page.locator('a[data-doc-link][href="/docs/FAQ"]').first();+ await entry.focus();+ await page.keyboard.press('Enter');+ const port = page.getByRole('heading', { name: 'How do I change the port?', exact: true });+ await port.waitFor();+ const text = await page.locator('article').innerText();+ if (label === 'parent') {+ assert.ok(text.includes('Use -p 8080:7655 in your run command.'));+ assert.ok(text.includes('Remove the env var to regain UI control.'));+ assert.ok(!text.includes('docker restart does not apply a new port mapping'));+ } else {+ for (const phrase of ['docker restart does not apply a new port mapping',+ 'preserving the same image, data mount and other settings',+ 'inside the Pulse container, not on the Proxmox host',+ 'does not necessarily erase the saved value', 'check both the warning and effective value'])+ assert.ok(text.replace(/\s+/g, ' ').includes(phrase), phrase);+ assert.ok(!text.includes('Remove the env var to regain UI control.'));+ }+ for (const [part, heading] of [['ports', port], ['overrides', page.getByRole('heading', {+ name: "Why can't I change settings in the UI?", exact: true,+ })]]) {+ await heading.scrollIntoViewIfNeeded();+ assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));+ const capture = `${engine}-${label}-${part}.jpg`;+ await page.screenshot({ path: path.join(artifacts, capture), type: 'jpeg', quality: 65 });+ captures.push(capture);+ }+ if (label === 'final') {+ for (const [name, target, heading] of [+ ['deployment-specific port checks', '/docs/TROUBLESHOOTING#port-change-didnt-take-effect', "Port change didn't take effect"],+ ['environment precedence', '/docs/CONFIGURATION#common-overrides-environment-variables', 'Common Overrides (Environment Variables)'],+ ['CORS checks', '/docs/TROUBLESHOOTING#cors-errors', 'CORS errors'],+ ]) {+ const link = page.getByRole('link', { name, exact: true });+ await link.focus();+ await page.keyboard.press('Enter');+ await page.getByRole('heading', { name: heading, exact: true }).waitFor();+ assert.ok(page.url().endsWith(target));+ await page.goBack();+ await page.getByRole('heading', { name: 'How do I change the port?', exact: true }).waitFor();+ }+ }+ assert.deepEqual(errors, []);+ await page.close();+ }+ results.push({ engine, version: browser.version(), width, tone, captures,+ parentGapReproduced: true, finalGuidanceRendered: true, keyboardLinks: 3, noBodyOverflow: true });+ await context.close();+ await browser.close();+ browser = undefined;+ }+ const result = { result: 'passed', playwrightVersion: require('playwright/package.json').version,+ parentSha256: digest(parent), finalSha256: digest(final), results,+ scope: 'FAQ rendering and recovery links, not installed port/override acceptance' };+ 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/FAQ.md b/frontend-modern/public/docs/FAQ.mdindex ad35e2b307..d057a40391 100644--- a/frontend-modern/public/docs/FAQ.md+++ b/frontend-modern/public/docs/FAQ.md@@ -21,8 +21,27 @@ run the unified agent directly.If you want Pulse to find servers automatically, enable discovery in **Settings → System → Network** and then review discovered servers in **Settings → Infrastructure**.### How do I change the port?-- **Systemd**: `sudo systemctl edit pulse`, add `Environment="FRONTEND_PORT=8080"`, restart.-- **Docker**: Use `-p 8080:7655` in your run command.++Distinguish Pulse's web listener from a container's published host port.+`FRONTEND_PORT` controls the listener (default **7655**); the separate+`PULSE_AGENT_INGEST_PORT` is not the web UI port.++- **Systemd / Proxmox LXC**: change the active Pulse service's managed port+ setting. For LXC, work inside the Pulse container, not on the Proxmox host.+ A unit or drop-in change needs a service-manager reload and a restart of that+ service during a suitable maintenance window.+- **Docker / Compose**: with the default listener, `8080:7655` publishes the UI+ on host port **8080**; it does not require changing `FRONTEND_PORT`. The+ repository's Compose file uses `PULSE_PORT` for this host-side mapping.+ Apply the change through your existing container manager's recreate/redeploy+ operation, preserving the same image, data mount and other settings.+ `docker restart` does not apply a new port mapping. Do not delete a data volume+ or replace your existing deployment with a fresh `docker run` command.++Update the reverse proxy's upstream port separately if needed; do not expose+Pulse directly or broadly open the firewall to bypass it. Follow the+[deployment-specific port checks](TROUBLESHOOTING.md#port-change-didnt-take-effect)+and keep full service environments and container inspections private.### Does updating the Pulse server update every agent immediately?@@ -38,7 +57,28 @@ update. Use **Settings → Infrastructure → Install on a host** for first instand v5-to-v6 upgrades. See [Unified Agent](UNIFIED_AGENT.md#auto-update).### Why can't I change settings in the UI?-If a setting is disabled with an amber warning, it's being overridden by an environment variable (e.g., `DISCOVERY_ENABLED`). Remove the env var to regain UI control.++A warning that names an environment variable means that deployment setting+manages the value, rather than the UI. If it is intentional, keep it and ask+the deployment administrator to change that setting; do not remove unrelated+authentication or security overrides.++To hand that particular setting back to the UI, remove only its override from+the active deployment source. Apply through the same deployment: environment+changes for Docker require recreation/redeployment, not `docker restart`; a+systemd unit or drop-in change needs a service-manager reload and restart.+Preserve the image, data mount, credentials and other settings. Merely editing+a file does not change the running process's environment.++Re-open Settings afterwards and check both the warning and effective value.+Removing an override does not necessarily erase the saved value underneath it+or turn the setting off. For example, a saved CORS allowlist can remain after+`ALLOWED_ORIGINS` is removed. See+[environment precedence](CONFIGURATION.md#common-overrides-environment-variables) and+[CORS checks](TROUBLESHOOTING.md#cors-errors). If no environment warning is+shown, retain the displayed error rather than assuming an override is the cause.+Do not post full environment, Compose or configuration dumps; they can contain+passwords and tokens.---diff --git a/scripts/tests/test_faq_deployment_docs.py b/scripts/tests/test_faq_deployment_docs.pynew file mode 100644index 0000000000..ad8dfd01e6--- /dev/null+++ b/scripts/tests/test_faq_deployment_docs.py@@ -0,0 +1,78 @@+#!/usr/bin/env python3+"""Bind the short deployment answers to source and the safer detailed paths.++Documentation checks, not an installed port change or environment cutover.+"""++from pathlib import Path+import unittest+++ROOT = Path(__file__).resolve().parents[2]+++def faq():+ return (ROOT / "docs/FAQ.md").read_text(encoding="utf-8")+++def answer(heading):+ return " ".join(faq().split(f"### {heading}\n", 1)[1].split("\n### ", 1)[0].split())+++class FAQDeploymentDocsTest(unittest.TestCase):+ def test_ports_distinguish_listener_mapping_and_server_host(self):+ text = answer("How do I change the port?")+ for phrase in ("`FRONTEND_PORT`", "default **7655**", "`PULSE_AGENT_INGEST_PORT`",+ "`8080:7655`", "`PULSE_PORT`", "inside the Pulse container",+ "not on the Proxmox host", "active Pulse service",+ "service-manager reload", "maintenance window"):+ with self.subTest(phrase=phrase):+ self.assertIn(phrase, text)+ config = (ROOT / "internal/config/config.go").read_text()+ self.assertIn('envconfig:"FRONTEND_PORT" default:"7655"', config)+ self.assertIn('envconfig:"PULSE_AGENT_INGEST_PORT"', config)+ compose = (ROOT / "docker-compose.yml").read_text()+ self.assertIn('${PULSE_PORT:-7655}:7655', compose)++ def test_existing_deployment_and_security_survive_port_change(self):+ text = answer("How do I change the port?")+ for phrase in ("existing container manager", "recreate/redeploy",+ "preserving the same image, data mount and other settings",+ "`docker restart` does not apply a new port mapping",+ "Do not delete a data volume", "fresh `docker run` command",+ "reverse proxy's upstream port separately",+ "do not expose Pulse directly", "inspections private",+ "TROUBLESHOOTING.md#port-change-didnt-take-effect"):+ with self.subTest(phrase=phrase):+ self.assertIn(phrase, text)++ def test_override_handover_is_scoped_applied_and_verified(self):+ text = answer("Why can't I change settings in the UI?")+ for phrase in ("warning that names an environment variable", "If it is intentional, keep it",+ "do not remove unrelated authentication or security overrides",+ "remove only its override", "active deployment source",+ "Docker require recreation/redeployment, not `docker restart`",+ "service-manager reload and restart", "Preserve the image, data mount, credentials",+ "does not change the running process's environment",+ "check both the warning and effective value",+ "does not necessarily erase the saved value", "`ALLOWED_ORIGINS`",+ "no environment warning", "Do not post full environment"):+ with self.subTest(phrase=phrase):+ self.assertIn(phrase, text)+ config = (ROOT / "internal/config/config.go").read_text()+ self.assertIn('cfg.EnvOverrides["ALLOWED_ORIGINS"] = true', config)+ form = (ROOT / "frontend-modern/src/components/Settings/DiscoverySettingsForm.tsx").read_text()+ self.assertIn('props.envOverrides().discoveryEnabled || props.savingDiscoverySettings()', form)+ self.assertIn('sectionPresentation().environmentOverrideMessage', form)++ def test_shipped_copy_and_detailed_destinations_exist(self):+ self.assertEqual(faq(), (ROOT / "frontend-modern/public/docs/FAQ.md").read_text())+ for guide, heading in (("TROUBLESHOOTING", "### Port change didn't take effect"),+ ("TROUBLESHOOTING", "### CORS errors"),+ ("CONFIGURATION", "### Common Overrides (Environment Variables)")):+ with self.subTest(guide=guide, heading=heading):+ self.assertIn(heading, (ROOT / "docs" / f"{guide}.md").read_text())+++if __name__ == "__main__":+ unittest.main()