From ea280c5a906032c7501920f3ce4211dd14d393c1 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Thu, 28 May 2026 10:48:53 -0400 Subject: [PATCH] docs(docs/install): strengthen Linux-only requirement on Docker install page (#25742) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Closes DOCS-68. Promotes the existing "Linux only" guidance on `docs/install/docker.md` from an easy-to-miss bullet point to a prominent `[!IMPORTANT]` callout, and briefly states *why* the page is Linux-only so macOS readers do not waste time on the `getent` / `--group-add` snippets. ## Why this re-scope vs. the original ticket The original DOCS-68 scope was "add a macOS `getent` alternative". On inspection, that framing has three problems: 1. The Requirements section already says "A Linux machine. For macOS devices, start Coder using the standalone binary," so macOS users are already redirected. The signal just lives in a bullet that is easy to overlook. 2. The `--group-add $DOCKER_GROUP` mechanism that drives the `getent` call is Linux-specific. macOS Docker runtimes (Docker Desktop, Colima, Rancher Desktop, Podman) use a VM and forward the socket differently; the flag does not translate cleanly to any of them. 3. Defining a canonical macOS Docker path is the scope of [DEVREL-22](https://linear.app/codercom/issue/DEVREL-22) (recommend Colima / Rancher / Podman alternatives in the Quick Start guide). DOCS-68 should not pre-empt that work. This PR narrows the fix to making the existing macOS guidance unmissable. A real macOS Docker install path can come as a separate follow-up once DEVREL-22 lands and the recommended runtime is settled.
Decision log * **(A) Close DOCS-68 as absorbed by DEVREL-22.** Rejected — the install page still has a discoverability problem that DEVREL-22 (Quick Start) will not fix. * **(B) Re-scope DOCS-68 to a narrow today-fix (this PR).** Selected. * **(C) Defer DOCS-68 until DEVREL-22 lands.** Rejected — the install page is shipping the weaker guidance every day until then.
> [!NOTE] > This is a docs-only change. No product code was modified. --- *Generated by Coder Agents on behalf of @nickvigilante.* --- docs/install/docker.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/install/docker.md b/docs/install/docker.md index 63bc5cd7b9..31a7628c7a 100644 --- a/docs/install/docker.md +++ b/docs/install/docker.md @@ -8,11 +8,16 @@ You can install and run Coder using the official Docker images published on - Docker. See the [official installation documentation](https://docs.docker.com/install/). -- A Linux machine. For macOS devices, start Coder using the - [standalone binary](./cli.md). +- A Linux host. - 2 CPU cores and 4 GB memory free on your machine. +> [!IMPORTANT] +> This guide is for **Linux** hosts only. The `getent` and `--group-add` +> Docker socket patterns used below are Linux-specific and do not translate +> cleanly to macOS Docker runtimes. For macOS, install Coder using the +> [standalone binary](./cli.md) instead. +
## Install Coder via `docker compose`