From f46abd17e20b3a2ae68407dcf19ae18eb9dbeb2e Mon Sep 17 00:00:00 2001 From: Ken Eucker Date: Sat, 15 Aug 2026 22:04:21 -0700 Subject: [PATCH] fix(install): explain that the bundle builder can't run under Git Bash MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `./install/build_offline_bundle_docker.sh` on Windows died with "No Docker socket at /var/run/docker.sock. Set NOMAD_DOCKER_SOCKET if yours lives elsewhere." — advice that cannot be followed, because there is no socket path to point at. Docker Desktop is reached over a named pipe. The docs claimed "Linux, macOS and Windows build machines all produce the same bundle", which is not true of Windows' native shells and is what sent the user down this path. Relaxing the `-S` guard would not fix it. The build starts further containers whose bind mounts are resolved by the host daemon, and MSYS rewrites the Unix-looking paths in every -v argument — so the socket mount, the repo mount and the output mount each need different treatment. Dropping the check just moves the failure somewhere less obvious. So: detect MSYS/MinGW/Cygwin and fail immediately with the actual remedy (build from WSL2, Linux or macOS), and correct the Windows claim in the docs. Real Git Bash support would mean reworking mount-path construction and is a separate piece of work. Co-Authored-By: Claude Opus 5 --- admin/docs/offline-install.md | 13 ++++++++++--- install/build_offline_bundle_docker.sh | 20 ++++++++++++++++++++ 2 files changed, 30 insertions(+), 3 deletions(-) diff --git a/admin/docs/offline-install.md b/admin/docs/offline-install.md index 80faaaa..29b8ab3 100644 --- a/admin/docs/offline-install.md +++ b/admin/docs/offline-install.md @@ -67,9 +67,16 @@ remote catalogs at runtime and is **not** covered; see The build machine needs **internet access and Docker** — that's the whole list. The entire build runs in containers, so no `git`, `bash` version, or GNU coreutils is required on the host, and the machine does not need to resemble the -target: Linux, macOS and Windows build machines all produce the same bundle, -because the package closure is resolved inside a container of the target -distribution. +target: the package closure is resolved inside a container of the target +distribution, so any build machine produces the same bundle. + +**Build from Linux, macOS, or WSL2.** The builder mounts the Docker socket and +the working directories into its container, which needs a real Unix socket and +un-rewritten paths. Windows *native* shells — Git Bash, MSYS, Cygwin — cannot +provide either: Docker Desktop is reached over a named pipe, and MSYS rewrites +the Unix-looking paths in every `-v` argument. The wrapper detects this and says +so rather than failing obscurely part-way through. On Windows, build from a WSL2 +distribution with Docker Desktop's WSL integration enabled. ```bash git clone https://github.com/Crosstalk-Solutions/project-nomad.git diff --git a/install/build_offline_bundle_docker.sh b/install/build_offline_bundle_docker.sh index 87f7b10..01f58e9 100755 --- a/install/build_offline_bundle_docker.sh +++ b/install/build_offline_bundle_docker.sh @@ -91,6 +91,26 @@ check_docker_available() { docker info > /dev/null 2>&1 || die "The Docker daemon is not reachable. Start Docker and try again." + # The build starts further containers, and their bind mounts are resolved by + # the host daemon — so the socket has to be mountable, not merely reachable. + # + # Under Git Bash / MSYS / Cygwin there is no Unix socket to mount: Docker + # Desktop is reached over a named pipe, and MSYS rewrites the Unix-looking + # paths in every -v argument on the way to the CLI. Relaxing this check alone + # does not make the build work there; it just moves the failure somewhere less + # obvious. Say so plainly instead. + case "$(uname -s 2>/dev/null || echo unknown)" in + MINGW*|MSYS*|CYGWIN*) + die "This wrapper cannot run under Git Bash / MSYS: Docker Desktop exposes a + named pipe rather than a mountable Unix socket, and MSYS rewrites the bind-mount + paths the build depends on. + + Build from a WSL2 Linux distribution with Docker Desktop's WSL integration + enabled (where /var/run/docker.sock exists), or from a Linux or macOS machine. + The bundle produced is identical wherever it is built." + ;; + esac + [[ -S "${DOCKER_SOCKET}" ]] || die "No Docker socket at ${DOCKER_SOCKET}. Set NOMAD_DOCKER_SOCKET if yours lives elsewhere." }