From 02ab14697f16b6691ecbcc904ce48f4af5fd200c Mon Sep 17 00:00:00 2001 From: anti Date: Fri, 24 Apr 2026 22:07:20 -0400 Subject: [PATCH] docs(troubleshooting): document ProtectHome as the most common buildx-wedge cause --- Troubleshooting.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/Troubleshooting.md b/Troubleshooting.md index a23cd71..d01dc86 100644 --- a/Troubleshooting.md +++ b/Troubleshooting.md @@ -78,6 +78,18 @@ mount | grep -c '/var/lib/docker/tmp/buildkit-mount' Anything past single digits is pathological. We've seen hosts sitting on hundreds after a few botched mass-scale topologies. +**Fix — sandboxed home (path under `/home/.../.docker`, count == 0).** + +The most common cause on a systemd-managed install: the API unit has `ProtectHome=read-only` and docker CLI can't write `~/.docker/buildx/activity/`. The error stderr will name a path under `/home/...`. Fix by redirecting docker's config root into a path that's already in `ReadWritePaths` (i.e. the install dir): + +``` +# /etc/systemd/system/decnet-api.service +Environment=DOCKER_CONFIG={{ install_dir }}/.docker +Environment=BUILDX_CONFIG={{ install_dir }}/.docker/buildx +``` + +Then `sudo systemctl daemon-reload && sudo systemctl restart decnet-api`. The shipped `deploy/decnet-api.service.j2` already includes these env vars — re-run `decnet init` to refresh the installed unit if your copy predates this fix. + **Fix — leaked mounts present (count > 0).** `prune -af && systemctl restart docker` is **not enough** — leaked mounts often outlive the daemon because zombie `buildkitd` / `containerd-shim` processes still hold them. Full recipe: