opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-21 12:44:32 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: add DOCKER_HOST guidance for non-default Docker socket paths (#26807)

Browse Source 
## What

Add `DOCKER_HOST` guidance for non-default Docker socket paths to two
pages:

- `docs/install/docker.md`: expands the **Cannot connect to the Docker
daemon**
troubleshooting section with the `DOCKER_HOST` fix and how to persist it
to
  your shell startup file.
- `docs/admin/templates/troubleshooting.md`: adds a concise **Cannot
connect to
the Docker daemon** entry that cross-references the install guide for
the full
  steps.

## Why

`install/docker.md` previously documented only the default socket path
(`/var/run/docker.sock`). 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, the daemon exposes its socket at a non-default path, so the
Coder
server cannot connect until `DOCKER_HOST` is set. The guidance frames
Colima as
one example, notes that default socket paths vary by tool, and persists
the
setting in a shell-agnostic way.

Generated by Coder Agents on behalf of @nickvigilante.
This commit is contained in:
Nick Vigilante
2026-07-08 11:33:02 -04:00
committed by GitHub
parent 8cf59d700f
commit 83acdaebd1
2 changed files with 26 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/templates/troubleshooting.md
+7
View File
@@ -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
docs/install/docker.md
+19
View File
@@ -114,6 +114,25 @@ daemon before creating a workspace from a Docker-based template. Refer to the
[Troubleshooting section of the get started guide](../get-started/index.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