diff --git a/docs/admin/templates/troubleshooting.md b/docs/admin/templates/troubleshooting.md index 147965ad9c1ad..7e2e9d6f2129b 100644 --- a/docs/admin/templates/troubleshooting.md +++ b/docs/admin/templates/troubleshooting.md @@ -171,6 +171,13 @@ 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. +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 ### Unable to query ContainerMemory diff --git a/docs/install/docker.md b/docs/install/docker.md index d10b5a18b36d9..3b6190580dc66 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -114,6 +114,25 @@ 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`. + +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) +export DOCKER_HOST="unix://${XDG_RUNTIME_DIR}/docker.sock" + +# Colima (macOS) +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. + ### Docker-based workspace is stuck in "Connecting..." Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See