docs(docs): improve Docker daemon troubleshooting for all platforms (#24922)

bpmct · web-flow · commit cfce751b8a56 · 2026-05-05T12:44:39.000-05:00
Improves the Docker daemon troubleshooting in the quickstart and Docker install docs: - Renames the quickstart entry from "Cannot connect to the Docker daemon on Linux" to cover all platforms. - Adds a plain-English explanation of what the error means (Docker is not installed or not running). - Adds tabbed macOS/Linux/Windows instructions to the quickstart (macOS and Windows were missing). - Simplifies the Linux steps to match what Step 1 of the quickstart already teaches. - Adds a matching entry to `docs/install/docker.md` with a cross-link to the quickstart for platform-specific steps. Supersedes #24907 which was closed without merging. Fixes https://linear.app/codercom/issue/DEVREL-23 > Generated with [Coder Agents](https://coder.com/agents)
diff --git a/docs/install/docker.md b/docs/install/docker.md
@@ -96,6 +96,19 @@ Replace `ghcr.io/coder/coder:latest` in the `docker run` command in the
 
 ## Troubleshooting
 
+### Cannot connect to the Docker daemon
+
+If you see an error like:
+
+```text
+Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
+```
+
+Docker is not installed or not running on the host. Install Docker and start the
+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.
+
 ### Docker-based workspace is stuck in "Connecting..."
 
 Ensure you have an externally-reachable `CODER_ACCESS_URL` set. See
diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md
@@ -257,48 +257,69 @@ advanced capabilities that Coder offers.
 
 ## Troubleshooting
 
-### Cannot connect to the Docker daemon on Linux
+### Cannot connect to the Docker daemon
+
+When creating a workspace from a Docker template, you may see an error like:
 
 ```text
 Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
 ```
 
-1. Install Docker for your system, if you haven't already done so:
+This means Docker is either not installed or not running on the machine where
+Coder is running. Docker must be running before you create a workspace from a
+Docker-based template.
+
+<div class="tabs">
+
+#### macOS
+
+1. If Docker Desktop is not installed,
+   [install it](https://docs.docker.com/desktop/setup/install/mac-install/) or
+   use Homebrew:
 
    ```shell
-   curl -sSL https://get.docker.com | sh
+   brew install --cask docker-desktop
    ```
 
-1. Set up the Docker daemon in rootless mode for your user to run Docker as a
-   non-privileged user:
+1. Open Docker Desktop and verify that it is running.
+
+#### Linux
+
+1. Install Docker, if you haven't already:
 
    ```shell
-   dockerd-rootless-setuptool.sh install
+   curl -sSL https://get.docker.com | sh
    ```
 
-   Depending on your system's dependencies, you might need to run other commands
-   before you retry this step. Read the output of this command for further
-   instructions.
+1. Start the Docker daemon:
 
-1. Assign your user to the Docker group:
+   ```shell
+   sudo systemctl start docker
+   ```
+
+1. Assign your user to the `docker` group so Coder can access the daemon
+   without root:
 
    ```shell
    sudo usermod -aG docker $USER
+   newgrp docker
    ```
 
-1. Confirm that the user has been added:
+1. Confirm the group membership:
 
    ```console
    $ groups
    docker sudo users
    ```
 
-   - Ubuntu users might not see the group membership update. In that case, run
-     the following command or reboot the machine:
+#### Windows
+
+1. If Docker Desktop is not installed,
+   [install it](https://docs.docker.com/desktop/install/windows-install/).
 
-     ```shell
-     newgrp docker
-     ```
+1. Open Docker Desktop and verify that it is running.
+
+</div>
 
 ### Can't start Coder server: Address already in use
 
