Merge pull request #1926 from link-assistant/issue-1914-0db0f6530c5c

fix(isolation): prevent DinD disk blowups and child image drift

Author: konard

.changeset/issue-1914-docker-isolation-fuse-overlayfs.md

@@ -0,0 +1,51 @@
+---
+'@link-assistant/hive-mind': patch
+---
+
+fix(isolation): default nested Docker daemon to fuse-overlayfs so multi-GB images fit on disk + add storage-driver/disk preflight diagnostics (#1914)
+
+`--isolation docker` was reopened after PR #1915: native Docker isolation and
+host-image passthrough now work, but the first isolated task on the >30 GB
+`konard/hive-mind-dind` image still died with:
+
+```
+failed to register layer: no space left on device
+```
+
+even though most layers reported `Already exists` (the daemon was correctly
+seeded — passthrough is working). The failure was during layer **registration**,
+not download.
+
+**Root cause (in this repo).** `Dockerfile.dind` baked `ENV
+DIND_STORAGE_DRIVER="vfs"` (commit 44d2c29e). `vfs` performs **no copy-on-write**:
+it materializes a full, independent copy of the entire filesystem for *every*
+layer, so a multi-GB image's on-disk footprint becomes the *sum* of all
+cumulative layer sizes — many times the image size — and overflows the disk.
+Worse, pinning the env var **defeated box-dind's storage-driver auto-detection**
+(`overlay2 → fuse-overlayfs → vfs`, with graceful fallback): box would otherwise
+have picked a copy-on-write driver here. `/dev/fuse` is present (the dind
+container runs `--privileged`), the `fuse-overlayfs` binary ships in box-dind,
+and `overlay` is in `/proc/filesystems` — so copy-on-write was available the
+whole time but was being bypassed by the `vfs` pin.
+
+**Fix.** `Dockerfile.dind` now pins `ENV DIND_STORAGE_DRIVER="fuse-overlayfs"` — a
+copy-on-write driver that also works overlay-on-overlay (the compatibility reason
+`vfs` was originally chosen; `overlay2` can fail on the overlay-backed hosts our
+deploys run on). Under `fuse-overlayfs`, registering a 498 MB top layer on a
+~30 GB base costs ~498 MB instead of ~30 GB, so the image fits. Empirically
+verified in the box-dind environment (`docs/case-studies/issue-1914/data/fuse-overlayfs-capability-proof.log`).
+
+**Self-diagnosing preflight.** `src/isolation-runner.lib.mjs` gained two probes —
+`checkDockerStorageDriver()` and `checkDockerDiskSpace()` — wired into
+`preflightDockerIsolation()`. Before running an isolated task it now warns, with
+an actionable remedy, when the nested daemon is on `vfs` (even if the image is
+already present) or when free space at the Docker data root is below 40 GiB, so
+the next operator hitting this gets a clear breadcrumb instead of a cryptic
+`no space left on device`. Both probes are best-effort and never throw.
+
+Added `tests/test-issue-1914-storage-driver-diagnostics.mjs` (34 assertions),
+extended `tests/test-issue-1914-preflight-passthrough.mjs` and
+`tests/test-docker-dind-variant.mjs`, refreshed `docs/DOCKER*.md`, and expanded
+the `docs/case-studies/issue-1914` case study with the reopen timeline, refined
+root-cause analysis, captured evidence, and an upstream observability request
+(link-foundation/box#104: warn when the nested daemon lands on `vfs`).

Dockerfile

@@ -20,6 +20,10 @@
 
 FROM konard/box:2.3.2
 ARG HIVE_MIND_VERSION=latest
+# Release builds pass the exact published package version here. Bake it as the
+# default child isolation image tag so a parent started via :latest still runs
+# Docker-isolated tasks on the same immutable release image.
+ENV HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG="${HIVE_MIND_VERSION}"
 
 # --- Environment variables ---
 # Set environment variables EARLY so they're available in subsequent RUN commands

Dockerfile.dind

@@ -20,9 +20,39 @@ ARG HIVE_MIND_VERSION=latest
 # --- Environment variables ---
 ENV HOME=/home/box
 ENV HIVE_MIND_IMAGE_VARIANT=dind
-# Prefer compatibility for nested Docker. overlay2 can fail on common
-# overlay-backed hosts; users can override this to overlay2 or fuse-overlayfs.
-ENV DIND_STORAGE_DRIVER="vfs"
+# Release builds pass the exact published package version here. Bake it as the
+# default child isolation image tag so a parent started via :latest still runs
+# Docker-isolated tasks on the same immutable release image.
+ENV HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG="${HIVE_MIND_VERSION}"
+# Nested-Docker storage driver. MUST be a copy-on-write driver for these images.
+#
+# The Hive Mind images are multiple gigabytes with many layers. `vfs` performs
+# NO copy-on-write: it materializes a full, independent copy of the entire
+# filesystem for every layer, so the on-disk footprint is the *sum* of all
+# cumulative layer sizes — many times the image size. On a >30 GB image that
+# overflows the disk and the first isolated `--isolation docker` task dies with
+# `failed to register layer: no space left on device` (issue #1914 reopen).
+#
+# `fuse-overlayfs` is the right default: it is copy-on-write (so the image
+# costs roughly its real size once, not a per-layer multiple) AND it works
+# overlay-on-overlay, which is the compatibility `vfs` was originally chosen
+# for — `overlay2` can fail on the overlay-backed hosts our deploys run on.
+# box-dind ships the `fuse-overlayfs` binary and Hive Mind launches the dind
+# container with `--privileged`, so /dev/fuse is available at runtime.
+#
+# NOTE: box-dind already auto-detects a driver (overlay2 -> fuse-overlayfs ->
+# vfs, with graceful fallback). Setting this env var OVERRIDES that detection
+# and pins one driver. The previous `vfs` value here defeated the auto-detect
+# and forced the no-copy-on-write driver — the exact cause of the #1914 reopen.
+# We pin `fuse-overlayfs` (not blank/auto) for determinism: it skips the
+# overlay2-on-overlay attempt that tends to fail in our nested deploys and
+# guarantees a copy-on-write daemon.
+#
+# Override only if you know your host: `-e DIND_STORAGE_DRIVER=overlay2` is
+# faster where nested overlay mounts are supported; `-e DIND_STORAGE_DRIVER=vfs`
+# is a last-resort compatibility fallback but uses many times the disk and is
+# the configuration that caused issue #1914.
+ENV DIND_STORAGE_DRIVER="fuse-overlayfs"
 ENV NVM_DIR="/home/box/.nvm"
 ENV PYENV_ROOT="/home/box/.pyenv"
 ENV BUN_INSTALL="/home/box/.bun"

coolify/Dockerfile

@@ -20,6 +20,10 @@
 
 FROM konard/box:2.3.2
 ARG HIVE_MIND_VERSION=latest
+# Release builds pass the exact published package version here. Bake it as the
+# default child isolation image tag so a parent started via :latest still runs
+# Docker-isolated tasks on the same immutable release image.
+ENV HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG="${HIVE_MIND_VERSION}"
 
 # --- Environment variables ---
 # Set environment variables EARLY so they're available in subsequent RUN commands

docs/DOCKER.hi.md

@@ -53,7 +53,12 @@ docker info
 docker run hello-world
 ```
 
-यह image overlay-backed hosts के साथ compatibility के लिए inner Docker daemon को default रूप से `DIND_STORAGE_DRIVER=vfs` पर चलाती है। जिन hosts पर nested overlay mounts supported हैं, वहां faster local runs के लिए `-e DIND_STORAGE_DRIVER=overlay2` pass करें।
+यह image inner Docker daemon को default रूप से `DIND_STORAGE_DRIVER=fuse-overlayfs` पर चलाती है। यह एक **copy-on-write** driver है, इसलिए कई गीगाबाइट की Hive Mind images डिस्क पर लगभग अपने असली आकार जितनी ही जगह (एक बार) लेती हैं — जबकि `vfs` हर layer की पूरी copy बनाता है और on-disk footprint को image आकार के कई गुना तक बढ़ा देता है, जिससे डिस्क `failed to register layer: no space left on device` के साथ भर जाती है ([issue #1914](https://github.com/link-assistant/hive-mind/issues/1914))। `fuse-overlayfs` overlay-on-overlay भी काम करता है (वही compatibility जिसके लिए शुरू में `vfs` चुना गया था), image में `fuse-overlayfs` binary पहले से मौजूद है, और Hive Mind DinD container को `--privileged` के साथ launch करता है, इसलिए `/dev/fuse` उपलब्ध रहता है। Override विकल्प:
+
+- `-e DIND_STORAGE_DRIVER=overlay2` — nested overlay mounts को support करने वाले hosts पर तेज़, लेकिन overlay-backed hosts पर fail हो सकता है;
+- `-e DIND_STORAGE_DRIVER=vfs` — केवल अंतिम विकल्प (compatibility fallback); कई गुना ज़्यादा डिस्क लेता है और यही वह configuration है जिसने issue #1914 पैदा किया।
+
+> **पुरानी `vfs` image पर container पहले से चल रहा है?** bot container के `docker run` में `-e DIND_STORAGE_DRIVER=fuse-overlayfs` जोड़ें और container को फिर से बनाएं — image rebuild की ज़रूरत नहीं।
 
 Shared hosts पर, उपलब्ध हो तो Sysbox runtime को प्राथमिकता दें:
 
@@ -65,13 +70,16 @@ DinD image `konard/hive-mind:latest` से अलग publish होती ह
 
 #### Host-image passthrough (मल्टी-GB images फिर से download होने से बचाएं)
 
-जब bot DinD image के अंदर `--isolation docker` के साथ चलता है, तो हर task एक _nested_
-`docker run konard/hive-mind-dind:latest …` के रूप में launch होता है। वह nested `docker run`
-**inner** dockerd से बात करता है, जिसका image store शुरू में **खाली** होता है (deploy
-`docker commit` से पहले `/var/lib/docker` को wipe कर देता है)। इसलिए Docker
-`Unable to find image '…' locally` report करता है और एक नई copy pull करता है — और Hive Mind
-images कई gigabytes की होती हैं, इसलिए पहला isolated task एक ऐसी image को re-download करने में
-बहुत समय लगा सकता है (या disk खत्म कर सकता है) जो **host के पास पहले से मौजूद** है। देखें
+जब bot release DinD image के अंदर `--isolation docker` के साथ चलता है, तो हर task एक _nested_
+`docker run konard/hive-mind-dind:<release-tag> …` के रूप में launch होता है। Release images
+published `HIVE_MIND_VERSION` से `HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG` bake करती हैं, इसलिए
+`konard/hive-mind-dind:latest` से started parent container भी child containers के लिए वही
+immutable release tag उपयोग करता है। वह nested `docker run` **inner** dockerd से बात करता है,
+जिसका image store शुरू में **खाली** होता है (deploy `docker commit` से पहले `/var/lib/docker`
+को wipe कर देता है)। इसलिए Docker `Unable to find image '…' locally` report करता है और एक
+नई copy pull करता है — और Hive Mind images कई gigabytes की होती हैं, इसलिए पहला isolated task
+एक ऐसी image को re-download करने में बहुत समय लगा सकता है (या disk खत्म कर सकता है) जो
+**host के पास पहले से मौजूद** है। देखें
 [issue #1914](https://github.com/link-assistant/hive-mind/issues/1914) और
 [#1879](https://github.com/link-assistant/hive-mind/issues/1879)।
 
@@ -101,22 +109,37 @@ default `public` mode में, केवल वे images copy होती 
 इसलिए host copy एक pulled/pushed image होनी चाहिए (केवल local `docker build` से बनी, बिना
 `RepoDigest` वाली image skip हो जाएगी — पहले उसे push करें या `all` उपयोग करें)।
 
+release deployments में final bot container start होने से पहले host पर exact child tag भी
+मौजूद होना चाहिए। केवल `:latest` pull करना अब काफी नहीं है, क्योंकि release image
+`HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG` pin करती है:
+
+```bash
+TAG="$(docker image inspect konard/hive-mind-dind:latest \
+  --format '{{range .Config.Env}}{{println .}}{{end}}' \
+  | sed -n 's/^HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG=//p' \
+  | tail -1)"
+docker pull "konard/hive-mind-dind:${TAG:-latest}"
+```
+
 **Startup preflight.** जब `--isolation docker` enabled होता है, bot startup पर inner daemon को
 probe करके result log करता है, ताकि misconfiguration task के बीच में surprise pull बनने के बजाय
 तुरंत सामने आ जाए:
 
 - ✅ image पहले से मौजूद → isolated tasks उसे reuse करते हैं (कोई pull नहीं);
 - ⚠️ socket mount **नहीं** है → यह आपको socket mount + allowlist जोड़ने को कहता है;
-- ⚠️ socket mounted है पर image अब भी absent → यह आपको passthrough mode/allowlist/digest जाँचने को कहता है।
+- ⚠️ socket mounted है पर image अब भी absent → यह आपको passthrough mode/allowlist/digest जाँचने को कहता है;
+- ⚠️ inner daemon `vfs` storage driver पर है → यह आपको `fuse-overlayfs` पर switch करने को कहता है (issue #1914 की disk-amplification root cause);
+- ⚠️ Docker data root पर कम free space और image अब भी absent → यह चेतावनी देता है कि आने वाला pull डिस्क खत्म कर सकता है।
 
 underlying `docker image inspect` traces के लिए bot को `--verbose` (या `TELEGRAM_BOT_VERBOSE=true`) के साथ चलाएं।
 
 **Manual fallback.** पहले से चल रहे container को तुरंत seed करने के लिए (या जब आप deployment नहीं बदल
 सकते), host image को inner daemon में copy करें:
 
 ```bash
+TAG="$(docker exec hive-mind printenv HIVE_MIND_DOCKER_ISOLATION_IMAGE_TAG || true)"
 node scripts/preload-dind-isolation-image.mjs \
-  --container hive-mind --image konard/hive-mind-dind:latest
+  --container hive-mind --image "konard/hive-mind-dind:${TAG:-latest}"
 ```
 
 यह `docker save … | docker exec -i <container> docker load` stream करता है ताकि tarball कभी disk पर