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.

Keep Docker healthcheck guidance free of arbitrary resource caps

pulse-triage[bot]449159525141
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 4d923a146e..a06e2d243f 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -108,24 +108,38 @@ services:
Metrics history stored this way is lost on container restart.
-<details>
-<summary><strong>Advanced: Resource Limits & Healthcheck</strong></summary>
+### Healthcheck and resource sizing
+
+Add this healthcheck to your **existing** `pulse` service; it is not a complete
+Compose file. Preserve the image, persistent data mount, network and other
+settings. Docker marks health failures as unhealthy; a healthcheck alone does
+not restart the container or prove that monitored workloads are healthy.
```yaml
services:
pulse:
- deploy:
- resources:
- limits:
- cpus: '0.5'
- memory: 256M
healthcheck:
test: ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"]
interval: 30s
timeout: 10s
retries: 3
```
-</details>
+
+**There is no universal CPU or memory limit for Pulse.** This example does not
+set one, and is not an instruction to remove an existing limit. Keep your
+deployment's current resource policy while investigating a problem. An
+undersized memory limit can cause an out-of-memory kill; a tight CPU quota can
+delay polling and notification delivery. Neither repairs an increased baseline.
+
+Choose limits from already available container readings during normal steady
+and busy periods, leaving headroom for the workload. Pulse process RSS is only
+part of the container's accounted memory, not a safe container limit by itself.
+Use the [bounded Docker statistics](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth)
+and [memory interpretation](TROUBLESHOOTING.md#memory-use-keeps-growing) if help
+is needed; an existing screenshot or unavailable reading is valid evidence.
+Do not restart, induce load, shorten retention or slow polling just to size the
+container or lower a reading. A higher steady baseline with unchanged monitoring
+is worth reporting, even when memory no longer grows.
---
diff --git a/frontend-modern/browser-tests/build-doc-command-help.mjs b/frontend-modern/browser-tests/build-doc-command-help.mjs
index dc590be4e0..203228a6a6 100644
--- a/frontend-modern/browser-tests/build-doc-command-help.mjs
+++ b/frontend-modern/browser-tests/build-doc-command-help.mjs
@@ -55,7 +55,7 @@ try {
for (const file of ['package.json', 'package-lock.json', 'tsconfig.json', 'index.html'])
binding.sources[file] = hash(fs.readFileSync(path.join(root, file)));
fs.mkdirSync(path.join(output, 'docs'), { recursive: true });
- for (const name of ['FAQ', 'UNIFIED_AGENT', 'TROUBLESHOOTING']) {
+ for (const name of ['FAQ', 'UNIFIED_AGENT', 'TROUBLESHOOTING', 'DOCKER']) {
const file = `public/docs/${name}.md`;
binding.sources[file] = hash(fs.readFileSync(path.join(root, file)));
fs.copyFileSync(path.join(root, file), path.join(output, 'docs', `${name}.md`));
diff --git a/frontend-modern/browser-tests/docker-resource-sizing.cjs b/frontend-modern/browser-tests/docker-resource-sizing.cjs
new file mode 100644
index 0000000000..e7fa23ff17
--- /dev/null
+++ b/frontend-modern/browser-tests/docker-resource-sizing.cjs
@@ -0,0 +1,123 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const http = require('node:http');
+const crypto = require('node:crypto');
+const assert = require('node:assert/strict');
+const { chromium, webkit } = require('playwright');
+const root = '/workspace';
+const frontend = path.join(root, 'frontend-modern');
+const evidence = path.join(root, 'tmp/doc-command-help');
+const preview = path.join(evidence, 'static');
+const hash = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+const bindingBytes = fs.readFileSync(path.join(preview, 'binding.json'));
+const binding = JSON.parse(bindingBytes);
+const result = { source: binding.source_sha, binding_sha256: hash(bindingBytes),
+ cases: [], captures: [], pageErrors: [], requests: [], served: [] };
+(async () => {
+ let server, browser;
+ try {
+ for (const [file, expected] of Object.entries(binding.sources))
+ assert.equal(hash(fs.readFileSync(path.join(frontend, file))), expected, file);
+ for (const [file, expected] of Object.entries(binding.artifacts))
+ assert.equal(hash(fs.readFileSync(path.join(preview, file))), expected, file);
+ result.source_inputs = Object.keys(binding.sources).length;
+ assert.equal(require('playwright/package.json').version, '1.56.1');
+ result.playwright = '1.56.1';
+ server = http.createServer((req, res) => {
+ const route = new URL(req.url, 'http://fixture.invalid').pathname;
+ let asset = route.slice(1);
+ if (route.startsWith('/docs/') && !route.endsWith('.md'))
+ asset = 'browser-tests/doc-command-help.html';
+ if (!Object.hasOwn(binding.artifacts, asset)) { res.writeHead(404); res.end(); return; }
+ const bytes = fs.readFileSync(path.join(preview, asset));
+ assert.equal(hash(bytes), binding.artifacts[asset]);
+ result.served.push({ route, asset, sha256: hash(bytes) });
+ const type = asset.endsWith('.md') ? 'text/markdown' : asset.endsWith('.css') ? 'text/css' :
+ asset.endsWith('.js') ? 'text/javascript' : 'text/html';
+ res.writeHead(200, { 'Content-Type': type, 'Cache-Control': 'no-store' }); res.end(bytes);
+ });
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ const origin = `http://127.0.0.1:${server.address().port}`;
+ for (const state of [
+ { name: 'desktop', width: 1280, height: 900, dark: false, engine: 'chromium' },
+ { name: 'phone', width: 375, height: 812, dark: true, engine: 'webkit' },
+ ]) {
+ browser = state.engine === 'webkit' ? await webkit.launch({ headless: true }) :
+ await chromium.launch({ headless: true, channel: 'chromium', args: ['--no-sandbox'] });
+ const browserVersion = browser.version();
+ const context = await browser.newContext({ viewport: { width: state.width, height: state.height },
+ isMobile: state.width < 500, hasTouch: state.width < 500 });
+ const page = await context.newPage();
+ page.on('pageerror', error => result.pageErrors.push(error.message));
+ page.on('request', req => result.requests.push({ path: new URL(req.url()).pathname, method: req.method() }));
+ await page.addInitScript(dark => {
+ document.addEventListener('DOMContentLoaded', () => document.documentElement.classList.toggle('dark', dark));
+ }, state.dark);
+ const activate = async locator => {
+ if (state.width < 500) await locator.tap();
+ else { await locator.focus(); await page.keyboard.press('Enter'); }
+ };
+ const capture = async (name, locator) => {
+ await locator.evaluate(el => window.scrollBy(0, el.getBoundingClientRect().top - 48));
+ await page.evaluate(() => new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve))));
+ assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= window.innerWidth), true, name);
+ const file = `docker-sizing-${state.name}-${name}.png`;
+ await page.screenshot({ path: path.join(evidence, file) });
+ result.captures.push({ file, sha256: hash(fs.readFileSync(path.join(evidence, file))), state });
+ };
+ await page.goto(`${origin}/docs/DOCKER#healthcheck-and-resource-sizing`);
+ await page.locator('#healthcheck-and-resource-sizing').waitFor();
+ const sizing = await page.locator('#healthcheck-and-resource-sizing').evaluate(heading => {
+ const section = document.createElement('section');
+ for (let node = heading.nextElementSibling; node && !/^H[123]$/.test(node.tagName); node = node.nextElementSibling)
+ section.append(node.cloneNode(true));
+ return { text: section.innerText || section.textContent, commands: [...section.querySelectorAll('pre code')].map(el => el.textContent) };
+ });
+ assert.equal(sizing.commands.length, 1);
+ assert.match(sizing.commands[0], /services:\s+\n?\s*pulse:\s+\n?\s*healthcheck:/);
+ assert.doesNotMatch(sizing.commands[0], /\b(deploy|resources|limits|memory|cpus|mem_limit):/);
+ assert.match(sizing.commands[0], /http:\/\/localhost:7655\/api\/health/);
+ for (const boundary of ['not a complete', 'not restart the container', 'no universal CPU or memory limit',
+ 'not an instruction to remove an existing limit', 'current resource policy', 'out-of-memory kill',
+ 'delay polling and notification delivery', 'Neither repairs an increased baseline',
+ 'not a safe container limit by itself', 'even when memory no longer grows'])
+ assert.equal(sizing.text.includes(boundary), true, boundary);
+ await capture('healthcheck', page.locator('#healthcheck-and-resource-sizing'));
+ const limits = page.locator('article p').filter({ hasText: 'There is no universal CPU or memory limit for Pulse.' });
+ assert.equal(await limits.count(), 1);
+ await capture('limits', limits);
+ await page.evaluate(() => window.__pi_docs_shell_marker = 'unchanged-shell');
+ for (const target of ['excessive-cpu-writes-or-database-growth', 'memory-use-keeps-growing']) {
+ await activate(page.locator(`article a[href="/docs/TROUBLESHOOTING#${target}"]`).first());
+ await page.waitForURL(`**/docs/TROUBLESHOOTING#${target}`);
+ await page.locator(`#${target}`).waitFor();
+ assert.equal(await page.locator(`#${target}`).evaluate(el => {
+ const box = el.getBoundingClientRect(); return box.top >= 0 && box.top < window.innerHeight;
+ }), true);
+ assert.equal(await page.evaluate(() => window.__pi_docs_shell_marker), 'unchanged-shell');
+ await page.goBack(); await page.waitForURL('**/docs/DOCKER#healthcheck-and-resource-sizing');
+ await page.locator('#healthcheck-and-resource-sizing').waitFor();
+ }
+ for (const name of ['DOCKER', 'TROUBLESHOOTING']) {
+ const response = await page.request.get(`${origin}/docs/${name}.md`);
+ assert.equal(response.status(), 200);
+ assert.equal(hash(await response.body()), binding.sources[`public/docs/${name}.md`]);
+ }
+ result.cases.push({ ...state, browserVersion, codeHasNoResourceCaps: true,
+ healthcheckPreserved: true, policyPreserved: true, diagnosticLinksAndHistory: true,
+ activation: state.width < 500 ? 'touch' : 'keyboard', servedBytesMatched: true, horizontalOverflow: false });
+ await context.close(); await browser.close(); browser = null;
+ }
+ assert.deepEqual(result.pageErrors, []);
+ assert.equal(result.requests.some(req => req.method !== 'GET' || req.path.startsWith('/api/') || req.path.startsWith('/ws')), false);
+ result.result = 'passed';
+ } catch (error) {
+ result.result = 'failed'; result.error = String(error.stack || error); process.exitCode = 1;
+ } finally {
+ if (browser) await browser.close(); result.browser_closed = true;
+ if (server) { await new Promise(resolve => server.close(resolve)); result.server_closed = true; }
+ fs.writeFileSync(path.join(evidence, 'docker-sizing-browser-result.json'), JSON.stringify(result, null, 2) + '\n');
+ console.log(JSON.stringify({ source: result.source, result: result.result, cases: result.cases.length,
+ captures: result.captures.length, browser_closed: result.browser_closed, server_closed: result.server_closed, error: result.error }));
+ }
+})().catch(error => { console.error(error); process.exitCode = 1; });
diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.md
index 4d923a146e..a06e2d243f 100644
--- a/frontend-modern/public/docs/DOCKER.md
+++ b/frontend-modern/public/docs/DOCKER.md
@@ -108,24 +108,38 @@ services:
Metrics history stored this way is lost on container restart.
-<details>
-<summary><strong>Advanced: Resource Limits & Healthcheck</strong></summary>
+### Healthcheck and resource sizing
+
+Add this healthcheck to your **existing** `pulse` service; it is not a complete
+Compose file. Preserve the image, persistent data mount, network and other
+settings. Docker marks health failures as unhealthy; a healthcheck alone does
+not restart the container or prove that monitored workloads are healthy.
```yaml
services:
pulse:
- deploy:
- resources:
- limits:
- cpus: '0.5'
- memory: 256M
healthcheck:
test: ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"]
interval: 30s
timeout: 10s
retries: 3
```
-</details>
+
+**There is no universal CPU or memory limit for Pulse.** This example does not
+set one, and is not an instruction to remove an existing limit. Keep your
+deployment's current resource policy while investigating a problem. An
+undersized memory limit can cause an out-of-memory kill; a tight CPU quota can
+delay polling and notification delivery. Neither repairs an increased baseline.
+
+Choose limits from already available container readings during normal steady
+and busy periods, leaving headroom for the workload. Pulse process RSS is only
+part of the container's accounted memory, not a safe container limit by itself.
+Use the [bounded Docker statistics](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth)
+and [memory interpretation](TROUBLESHOOTING.md#memory-use-keeps-growing) if help
+is needed; an existing screenshot or unavailable reading is valid evidence.
+Do not restart, induce load, shorten retention or slow polling just to size the
+container or lower a reading. A higher steady baseline with unchanged monitoring
+is worth reporting, even when memory no longer grows.
---
diff --git a/scripts/tests/test_docker_resource_sizing_docs.py b/scripts/tests/test_docker_resource_sizing_docs.py
new file mode 100644
index 0000000000..e694206a61
--- /dev/null
+++ b/scripts/tests/test_docker_resource_sizing_docs.py
@@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+"""Keep the optional Docker healthcheck free of unqualified resource caps.
+
+This validates the copyable configuration and its safety context, not Pulse's
+memory requirement, Docker enforcement or reporter recovery.
+"""
+
+import json
+from pathlib import Path
+import re
+import unittest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def section():
+ return (ROOT / "docs/DOCKER.md").read_text().split(
+ "### Healthcheck and resource sizing\n", 1
+ )[1].split("\n---", 1)[0]
+
+
+class DockerResourceSizingDocsTest(unittest.TestCase):
+ def test_shipped_document_matches_the_source(self):
+ self.assertEqual((ROOT / "docs/DOCKER.md").read_bytes(),
+ (ROOT / "frontend-modern/public/docs/DOCKER.md").read_bytes())
+
+ def test_healthcheck_does_not_apply_arbitrary_cpu_or_memory_caps(self):
+ blocks = re.findall(r"```yaml\n(.*?)```", section(), re.S)
+ self.assertEqual(len(blocks), 1)
+ self.assertEqual(blocks[0].splitlines()[:3],
+ ["services:", " pulse:", " healthcheck:"])
+ self.assertNotRegex(blocks[0], r"(?m)^\s*(deploy|resources|limits|cpus|memory|mem_limit):")
+ test = re.search(r"(?m)^ test: (.*)$", blocks[0]).group(1)
+ self.assertEqual(json.loads(test),
+ ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"])
+ self.assertIn(" interval: 30s\n timeout: 10s\n retries: 3", blocks[0])
+
+ def test_limits_and_health_are_not_sold_as_monitoring_recovery(self):
+ text = section()
+ for fact in ("not a complete", "not restart the container", "no universal CPU or memory limit",
+ "not an instruction to remove an existing limit", "current resource policy",
+ "out-of-memory kill", "delay polling and notification delivery",
+ "Neither repairs an increased baseline", "not a safe container limit by itself",
+ "existing screenshot or unavailable reading is valid evidence",
+ "Do not restart, induce load, shorten retention or slow polling",
+ "even when memory no longer grows"):
+ self.assertIn(fact, text)
+
+ def test_safe_measurement_links_exist_in_the_actual_help(self):
+ source = (ROOT / "docs/TROUBLESHOOTING.md").read_text()
+ for anchor, heading in (
+ ("excessive-cpu-writes-or-database-growth", "#### Excessive CPU, writes or database growth"),
+ ("memory-use-keeps-growing", "#### Memory use keeps growing"),
+ ):
+ self.assertIn(f"TROUBLESHOOTING.md#{anchor}", section())
+ self.assertIn(heading, source)
+
+
+if __name__ == "__main__":
+ unittest.main()