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
Distinguish Docker image storage from retained Pulse data
pulse-triage[bot]3baacbebc1ac
diff --git a/docs/DOCKER.md b/docs/DOCKER.mdindex 978af84011..245b0df58f 100644--- a/docs/DOCKER.md+++ b/docs/DOCKER.md@@ -1,6 +1,7 @@# 🐳 Docker Guide-Pulse is distributed as a lightweight, Alpine-based Docker image.+Pulse is distributed as an Alpine-based Docker image. Image storage and Pulse's+persistent data are separate; see [image size and disk use](#image-size-and-disk-use).> **Paid Pulse Pro / Relay / legacy customers:** The public `rcourtman/pulse`> Docker image is the community build. It can accept an activation key, but it@@ -71,6 +72,46 @@ shown on <https://pulserelay.pro/download.html>.---+## Image size and disk use++A registry download, a local image and a container's data do not measure the+same storage. Before comparing sizes, keep the exact image reference or digest,+platform (for example, `linux/amd64` or `linux/arm64`), displayed units and the+tool's measurement label together. A mutable tag such as `latest` is not an+immutable comparison, and a multi-platform image index is not one platform's+image.++| Reading | What it measures | What it does not establish |+| --- | --- | --- |+| Registry or pull download size | Usually the compressed layers for the selected platform; cached layers may not need downloading again | The unpacked local image size or space used by Pulse's data |+| Local image size | The image's stored layers, with accounting depending on the Docker version and image store | Exclusive disk use: layers can be shared between images and tags, and some stores retain both compressed and unpacked content |+| Container writable-layer size | Changes made in that container above the image | Mounted volume or bind-mount contents; it is not the image's download size |+| Pulse's mounted `/data` | Persistent configuration, credentials and retained history in the deployment's volume or bind mount | Image size; replacing an image does not shrink or back up this data |++Image layers are retained even when a later layer replaces a file or changes+its ownership. The final visible filesystem can therefore be smaller than the+stored image. Conversely, adding the sizes of several local tags can count+shared layers more than once. Keep **GB** (decimal) and **GiB** (binary), or a+tool's rounded **MB** label, distinct; do not infer a leak or a reduction from+unmatched readings.++Use details already available in your deployment manager. The+[update checks](#-updates) show a narrow, read-only way to identify a container's+configured image and image ID; a Compose file or a pulled tag alone does not+establish which image the container is running. Existing observations are enough+for a report: include the size and its label, image/platform if known, and+whether it concerns the image, writable layer or persistent data. Unknown is+valid; do not pull or build another image, recreate a container or export full+inspect/Compose output just to complete the comparison.++**Do not prune images, delete volumes or clear `/data` to diagnose image size.**+Keep the previous image and consistent data backup needed for+[update recovery](#-updates). An image-layer repair does not reclaim old images,+shrink retained history or establish how much space an installed update will+free. For unexpected ongoing writes or growth, use the separate+[CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth),+without changing retention or restarting to obtain a smaller reading.+## ⚙️ ConfigurationPulse is configured via the UI (`system.json`) with optional environment overrides.diff --git a/frontend-modern/public/docs/DOCKER.md b/frontend-modern/public/docs/DOCKER.mdindex 978af84011..245b0df58f 100644--- a/frontend-modern/public/docs/DOCKER.md+++ b/frontend-modern/public/docs/DOCKER.md@@ -1,6 +1,7 @@# 🐳 Docker Guide-Pulse is distributed as a lightweight, Alpine-based Docker image.+Pulse is distributed as an Alpine-based Docker image. Image storage and Pulse's+persistent data are separate; see [image size and disk use](#image-size-and-disk-use).> **Paid Pulse Pro / Relay / legacy customers:** The public `rcourtman/pulse`> Docker image is the community build. It can accept an activation key, but it@@ -71,6 +72,46 @@ shown on <https://pulserelay.pro/download.html>.---+## Image size and disk use++A registry download, a local image and a container's data do not measure the+same storage. Before comparing sizes, keep the exact image reference or digest,+platform (for example, `linux/amd64` or `linux/arm64`), displayed units and the+tool's measurement label together. A mutable tag such as `latest` is not an+immutable comparison, and a multi-platform image index is not one platform's+image.++| Reading | What it measures | What it does not establish |+| --- | --- | --- |+| Registry or pull download size | Usually the compressed layers for the selected platform; cached layers may not need downloading again | The unpacked local image size or space used by Pulse's data |+| Local image size | The image's stored layers, with accounting depending on the Docker version and image store | Exclusive disk use: layers can be shared between images and tags, and some stores retain both compressed and unpacked content |+| Container writable-layer size | Changes made in that container above the image | Mounted volume or bind-mount contents; it is not the image's download size |+| Pulse's mounted `/data` | Persistent configuration, credentials and retained history in the deployment's volume or bind mount | Image size; replacing an image does not shrink or back up this data |++Image layers are retained even when a later layer replaces a file or changes+its ownership. The final visible filesystem can therefore be smaller than the+stored image. Conversely, adding the sizes of several local tags can count+shared layers more than once. Keep **GB** (decimal) and **GiB** (binary), or a+tool's rounded **MB** label, distinct; do not infer a leak or a reduction from+unmatched readings.++Use details already available in your deployment manager. The+[update checks](#-updates) show a narrow, read-only way to identify a container's+configured image and image ID; a Compose file or a pulled tag alone does not+establish which image the container is running. Existing observations are enough+for a report: include the size and its label, image/platform if known, and+whether it concerns the image, writable layer or persistent data. Unknown is+valid; do not pull or build another image, recreate a container or export full+inspect/Compose output just to complete the comparison.++**Do not prune images, delete volumes or clear `/data` to diagnose image size.**+Keep the previous image and consistent data backup needed for+[update recovery](#-updates). An image-layer repair does not reclaim old images,+shrink retained history or establish how much space an installed update will+free. For unexpected ongoing writes or growth, use the separate+[CPU and write-rate checks](TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth),+without changing retention or restarting to obtain a smaller reading.+## ⚙️ ConfigurationPulse is configured via the UI (`system.json`) with optional environment overrides.diff --git a/scripts/tests/test_docker_resource_sizing_docs.py b/scripts/tests/test_docker_resource_sizing_docs.pyindex e694206a61..7a99453ecd 100644--- a/scripts/tests/test_docker_resource_sizing_docs.py+++ b/scripts/tests/test_docker_resource_sizing_docs.py@@ -56,6 +56,36 @@ class DockerResourceSizingDocsTest(unittest.TestCase):self.assertIn(f"TROUBLESHOOTING.md#{anchor}", section())self.assertIn(heading, source)+ def test_image_storage_is_not_sold_as_lightweight_or_persistent_data(self):+ guide = (ROOT / "docs/DOCKER.md").read_text()+ self.assertNotIn("lightweight", guide.split("\n## ", 1)[0])+ text = guide.split("## Image size and disk use\n", 1)[1].split("\n## ", 1)[0]+ for fact in ("compressed layers", "cached layers", "Docker version and image store",+ "shared between images and tags", "Container writable-layer size",+ "Mounted volume or bind-mount contents", "Persistent configuration, credentials",+ "replacing an image does not shrink or back up this data",+ "GB** (decimal)", "GiB** (binary)", "changes\nits ownership"):+ with self.subTest(fact=fact):+ self.assertIn(fact, text)++ def test_image_comparison_preserves_state_and_uses_existing_evidence(self):+ guide = (ROOT / "docs/DOCKER.md").read_text()+ text = guide.split("## Image size and disk use\n", 1)[1].split("\n## ", 1)[0]+ for fact in ("exact image reference or digest", "linux/amd64", "linux/arm64",+ "measurement label", "multi-platform image index",+ "configured image and image ID", "Unknown is\nvalid",+ "do not pull or build another image", "export full\ninspect/Compose output",+ "Do not prune images, delete volumes or clear `/data`",+ "Keep the previous image and consistent data backup",+ "does not reclaim old images", "without changing retention or restarting"):+ with self.subTest(fact=fact):+ self.assertIn(fact, text)+ # No fresh diagnostic command, broad inspect or cleanup recipe is added.+ self.assertNotIn("```", text)+ self.assertIn("docker inspect pulse --format '{{.Config.Image}} {{.Image}}'", guide)+ self.assertIn("## 🔄 Updates", guide)+ self.assertIn("TROUBLESHOOTING.md#excessive-cpu-writes-or-database-growth", text)+if __name__ == "__main__":unittest.main()