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.

Preserve existing deployments in FAQ configuration help

pulse-triage[bot]5b72730caf8f
diff --git a/docs/FAQ.md b/docs/FAQ.md
index 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 inst
and 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.cjs
new file mode 100644
index 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.md
index 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 inst
and 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.py
new file mode 100644
index 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()