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 Docker healthcheck guidance free of arbitrary resource caps
pulse-triage[bot]449159525141
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 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.```yamlservices:pulse:- deploy:- resources:- limits:- cpus: '0.5'- memory: 256Mhealthcheck:test: ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"]interval: 30stimeout: 10sretries: 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.mjsindex 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.cjsnew file mode 100644index 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.mdindex 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.```yamlservices:pulse:- deploy:- resources:- limits:- cpus: '0.5'- memory: 256Mhealthcheck:test: ["CMD", "wget", "--spider", "-q", "http://localhost:7655/api/health"]interval: 30stimeout: 10sretries: 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.pynew file mode 100644index 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()