Thanks to visit codestin.com
Credit goes to github.com

Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
nickvigilante merged 3 commits into from
Jul 8, 2026
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c89a57c
docs: add Colima DOCKER_HOST guidance to Docker install and troublesh…
nickvigilante Jun 29, 2026
6905e1c
docs: generalize Docker socket guidance beyond macOS Colima
nickvigilante Jun 29, 2026
e57f919
docs: apply prose style guide to DOCKER_HOST guidance
nickvigilante Jun 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/admin/templates/troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
19 changes: 19 additions & 0 deletions docs/install/docker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading