From c89a57cde10a80ebdf15639fc0f24b9466e95920 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 29 Jun 2026 14:03:10 +0000 Subject: [PATCH 1/3] docs: add Colima DOCKER_HOST guidance to Docker install and troubleshooting When the Docker daemon exposes its socket at a non-default path (common with Colima and other Docker Desktop alternatives on macOS), the Coder server cannot connect until DOCKER_HOST points at the right socket. Add this guidance to the "Cannot connect to the Docker daemon" section of the Docker install guide, and add a concise cross-referenced entry in the template troubleshooting guide. Refs: DOCS-466 Filed via Coder Agents on Nick's behalf. --- docs/admin/templates/troubleshooting.md | 11 +++++++++++ docs/install/docker.md | 14 ++++++++++++++ 2 files changed, 25 insertions(+) diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md index 147965ad9c1..5a18c5de0b7 100644 --- a/docs/admin/templates/troubleshooting.md +++ b/docs/admin/templates/troubleshooting.md @@ -171,6 +171,17 @@ to optimize your templates based on this data. ![Workspace build timings UI](../../images/admin/templates/troubleshooting/workspace-build-timings-ui.png) +## Cannot connect to the Docker daemon + +If a Docker-based template fails to provision with an error like +`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`, the Coder +host cannot reach the Docker socket. Confirm that Docker is installed and running +on the host. With [Colima](https://colima.run) or another Docker Desktop +alternative on macOS, the daemon exposes its socket at a non-default path, so set +`DOCKER_HOST` before you start the Coder server. See +[Cannot connect to the Docker daemon](../../install/docker.md#cannot-connect-to-the-docker-daemon) +for the full steps. + ## Docker Workspaces on Raspberry Pi OS ### Unable to query ContainerMemory diff --git a/docs/install/docker.md b/docs/install/docker.md index d10b5a18b36..8010fde30a2 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -114,6 +114,20 @@ daemon before creating a workspace from a Docker-based template. Refer to the [quickstart troubleshooting](../tutorials/quickstart.md#cannot-connect-to-the-docker-daemon) for platform-specific steps. +If Docker is installed and running but Coder still cannot connect, the daemon +may expose its socket at a non-default path. This is common with +[Colima](https://colima.run) and other Docker Desktop alternatives on macOS. +Point Coder at the correct socket with `DOCKER_HOST`, and append it to your +shell profile so it survives new shells and restarts: + +```sh +export DOCKER_HOST="unix://${HOME}/.config/colima/default/docker.sock" +echo 'export DOCKER_HOST="unix://${HOME}/.config/colima/default/docker.sock"' >> ~/.zshrc +``` + +Run `colima status` (or your runtime's equivalent) to confirm the socket path, +then restart the Coder server. + ### Docker-based workspace is stuck in "Connecting..." Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See From 6905e1c281b96b9b03a18c01155c0608050f6cb3 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 29 Jun 2026 14:33:05 +0000 Subject: [PATCH 2/3] docs: generalize Docker socket guidance beyond macOS Colima Address review feedback on the DOCKER_HOST troubleshooting guidance: - Frame the non-default socket case as cross-platform (rootless Docker on Linux, plus Colima, Podman, or Rancher Desktop on macOS) instead of "Docker Desktop alternatives on macOS". - Present Colima as one example and add a caveat that tools use different default socket paths, with a rootless Docker sample alongside Colima. - Make persistence shell-agnostic: give the export command, then point at the reader's shell startup file instead of assuming Bash or Zsh. - Correct the Colima socket path to ~/.colima/default/docker.sock. Filed via Coder Agents on Nick's behalf. Refs: DOCS-466 --- docs/admin/templates/troubleshooting.md | 6 +++--- docs/install/docker.md | 25 +++++++++++++++++-------- 2 files changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md index 5a18c5de0b7..d98a19bccae 100644 --- a/docs/admin/templates/troubleshooting.md +++ b/docs/admin/templates/troubleshooting.md @@ -176,9 +176,9 @@ to optimize your templates based on this data. If a Docker-based template fails to provision with an error like `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`, the Coder host cannot reach the Docker socket. Confirm that Docker is installed and running -on the host. With [Colima](https://colima.run) or another Docker Desktop -alternative on macOS, the daemon exposes its socket at a non-default path, so set -`DOCKER_HOST` before you start the Coder server. See +on the host. If you run Docker through rootless Docker, [Colima](https://colima.run), +Podman, or a similar tool, the daemon may expose its socket at a non-default +path, so set `DOCKER_HOST` to point at it. See [Cannot connect to the Docker daemon](../../install/docker.md#cannot-connect-to-the-docker-daemon) for the full steps. diff --git a/docs/install/docker.md b/docs/install/docker.md index 8010fde30a2..b32a4f582be 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -115,18 +115,27 @@ daemon before creating a workspace from a Docker-based template. Refer to the for platform-specific steps. If Docker is installed and running but Coder still cannot connect, the daemon -may expose its socket at a non-default path. This is common with -[Colima](https://colima.run) and other Docker Desktop alternatives on macOS. -Point Coder at the correct socket with `DOCKER_HOST`, and append it to your -shell profile so it survives new shells and restarts: +may expose its socket at a path other than `/var/run/docker.sock`. This can +happen on any operating system when Docker runs through a tool that uses a +per-user socket, such as rootless Docker on Linux, or Colima, Podman, or Rancher +Desktop on macOS. Point Coder at the right socket with `DOCKER_HOST`. + +Find the socket path first. For example, run `colima status` for Colima, or +`docker context inspect` to read the endpoint of the active Docker context. The +samples below are examples only; tools use different default paths, so check +your tool's documentation for the value to set: ```sh -export DOCKER_HOST="unix://${HOME}/.config/colima/default/docker.sock" -echo 'export DOCKER_HOST="unix://${HOME}/.config/colima/default/docker.sock"' >> ~/.zshrc +# rootless Docker (Linux) +export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock" + +# Colima (macOS) +export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock" ``` -Run `colima status` (or your runtime's equivalent) to confirm the socket path, -then restart the Coder server. +To persist the setting, add the `export` line to your shell's startup file, such +as `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`. Then restart the +Coder server. ### Docker-based workspace is stuck in "Connecting..." From e57f919d4b34ee9659bf34db186fd29989053a69 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Mon, 29 Jun 2026 14:48:03 +0000 Subject: [PATCH 3/3] docs: apply prose style guide to DOCKER_HOST guidance Apply docs/.style/style-guide conventions to the DOCKER_HOST troubleshooting content added in this branch: - One sentence per line (formatting.md) in both the install guide and the template-troubleshooting sections. - Use "refer to" instead of "see" for the cross-reference in troubleshooting.md (word-choice.md). - Reword the example caveat to state that default socket paths vary by tool and the reader should consult their tool's documentation. Filed via Coder Agents on Nick's behalf. Refs: DOCS-466 --- docs/admin/templates/troubleshooting.md | 12 ++++-------- docs/install/docker.md | 20 ++++++++------------ 2 files changed, 12 insertions(+), 20 deletions(-) diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md index d98a19bccae..7e2e9d6f212 100644 --- a/docs/admin/templates/troubleshooting.md +++ b/docs/admin/templates/troubleshooting.md @@ -173,14 +173,10 @@ to optimize your templates based on this data. ## Cannot connect to the Docker daemon -If a Docker-based template fails to provision with an error like -`Cannot connect to the Docker daemon at unix:///var/run/docker.sock`, the Coder -host cannot reach the Docker socket. Confirm that Docker is installed and running -on the host. If you run Docker through rootless Docker, [Colima](https://colima.run), -Podman, or a similar tool, the daemon may expose its socket at a non-default -path, so set `DOCKER_HOST` to point at it. See -[Cannot connect to the Docker daemon](../../install/docker.md#cannot-connect-to-the-docker-daemon) -for the full steps. +If a Docker-based template fails to provision with an error like `Cannot connect to the Docker daemon at unix:///var/run/docker.sock`, the Coder host cannot reach the Docker socket. +Confirm that Docker is installed and running on the host. +If you run Docker through rootless Docker, [Colima](https://colima.run), Podman, or a similar tool, the daemon may expose its socket at a non-default path, so set `DOCKER_HOST` to point at it. +Refer to [Cannot connect to the Docker daemon](../../install/docker.md#cannot-connect-to-the-docker-daemon) for the full steps. ## Docker Workspaces on Raspberry Pi OS diff --git a/docs/install/docker.md b/docs/install/docker.md index b32a4f582be..3b6190580dc 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -114,16 +114,13 @@ daemon before creating a workspace from a Docker-based template. Refer to the [quickstart troubleshooting](../tutorials/quickstart.md#cannot-connect-to-the-docker-daemon) for platform-specific steps. -If Docker is installed and running but Coder still cannot connect, the daemon -may expose its socket at a path other than `/var/run/docker.sock`. This can -happen on any operating system when Docker runs through a tool that uses a -per-user socket, such as rootless Docker on Linux, or Colima, Podman, or Rancher -Desktop on macOS. Point Coder at the right socket with `DOCKER_HOST`. +If Docker is installed and running but Coder still cannot connect, the daemon may expose its socket at a path other than `/var/run/docker.sock`. +This can happen on any operating system when Docker runs through a tool that uses a per-user socket, such as rootless Docker on Linux, or Colima, Podman, or Rancher Desktop on macOS. +Point Coder at the right socket with `DOCKER_HOST`. -Find the socket path first. For example, run `colima status` for Colima, or -`docker context inspect` to read the endpoint of the active Docker context. The -samples below are examples only; tools use different default paths, so check -your tool's documentation for the value to set: +Find the socket path first. +For example, run `colima status` for Colima, or `docker context inspect` to read the endpoint of the active Docker context. +Default socket paths vary by tool, so consult your tool's documentation and treat the following as examples only: ```sh # rootless Docker (Linux) @@ -133,9 +130,8 @@ export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock" export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock" ``` -To persist the setting, add the `export` line to your shell's startup file, such -as `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`. Then restart the -Coder server. +To persist the setting, add the `export` line to your shell's startup file, such as `~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`. +Then restart the Coder server. ### Docker-based workspace is stuck in "Connecting..."