docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop (#26106)#26120
Merged
Merged
Conversation
… besides Docker Desktop (#26106) Replaces the quickstart's "Install Docker" step with a runtime-agnostic "Install a container runtime" step, and switches the per-platform defaults to free, lightweight options that avoid Docker Desktop's cost and overhead. A callout above the OS tabs names Colima, Rancher Desktop, Podman, and Docker Desktop as valid runtimes and tells readers to skip ahead if they already have one running. The default install path per platform is now: - Linux: Docker Engine (unchanged from the previous doc) - macOS: Colima with the Docker CLI - Windows: Podman Desktop The "Cannot connect to the Docker daemon" troubleshooting subsections are updated to match the new defaults. Closes [DEVREL-22](https://linear.app/codercom/issue/DEVREL-22/recommend-orbstackcolimarancher-desktoppodman-as-docker-desktop). A follow-up Linear issue will track a deeper "Docker runtime alternatives" reference page covering OrbStack (with its commercial-license caveat), Rancher Desktop, and CLI Podman. <details> <summary>Implementation proposal and pre-mortem</summary> # DEVREL-22 proposal: Replace "Install Docker" with "Install a container runtime" Linear: [DEVREL-22](https://linear.app/codercom/issue/DEVREL-22/recommend-orbstackcolimarancher-desktoppodman-as-docker-desktop) Repo: `coder/coder` Branch: `vigilante/devrel-22-recommend-orbstackcolimarancher-desktoppodman-as-docker` Primary file: `docs/tutorials/quickstart.md` ## Summary Rename Step 1 of the quickstart from "Install Docker and set up permissions" to "Install a container runtime", add a callout that any Docker-compatible runtime works, and switch the per-platform default to the lightest free path on each OS. Keep Docker Desktop, OrbStack, and Rancher Desktop as documented alternatives, but not as the primary recommendation. The deeper "alternatives" reference page is a follow-up. ## Why - Docker Desktop is slow on macOS/Windows and requires a paid license for most commercial use. - The Coder Quickstart template only needs the Docker daemon, not Docker Desktop's GUI. - No single tool satisfies "curl install + cross-platform + free + minimal setup", so a per-platform recommendation is the honest answer. ## Per-platform defaults | Platform | Default in quickstart | Why | |----------|----------------------|-----| | Linux | Docker Engine via `curl -sSL https://get.docker.com \| sh` | Already in the doc, already a curl one-liner, already free. No change. | | macOS | Colima | Two commands (`brew install colima docker`, `colima start`), free for commercial use, exposes `/var/run/docker.sock` so the Coder template needs zero env vars. | | Windows | Podman Desktop | Free, handles WSL2 prereq and `podman machine` setup through the GUI, sets up Docker socket compatibility. Lighter than Docker Desktop, simpler than CLI Podman + `DOCKER_HOST`. | ## Pre-mortem 1. **Coder Quickstart template assumes `/var/run/docker.sock`.** Colima symlinks it on macOS. Podman Desktop on Windows enables Docker socket compatibility by default, so the template's Docker provider should reach the daemon without `DOCKER_HOST` gymnastics. 2. **External links into `quickstart#step-1-install-docker-and-set-up-permissions`.** A grep of `docs/` and `site/` found no internal references to the old anchor. Blog posts or external links may land at the top of the page after the rename; acceptable for this scope. 3. **Brew assumption on macOS.** Recommending `brew install colima docker` assumes Homebrew. The callout links to brew.sh so users without it can install Homebrew first. 4. **WSL2 on Windows.** Podman Desktop's onboarding installs WSL2 if missing. Corporate-managed machines that block WSL2 can fall back to other runtimes named in the callout. 5. **Onboarding tone shift.** "Container runtime" is more abstract than "Docker." The callout names Docker Desktop as a runtime first, so the unfamiliar phrase is anchored immediately. 6. **OrbStack license trap.** OrbStack is intentionally not in the quickstart's default path because it is paid for commercial use. It will be mentioned on the future alternatives page with the license caveat called out explicitly. ## Out of scope (follow-up issues) - New "Docker runtime alternatives" reference page covering OrbStack, Rancher Desktop, CLI Podman, with license and compatibility notes. - `docs/install/docker.md` updates. That page is about installing Coder server in a Docker container, which is a separate concern. - Updating the `coder/skills` `setup` skill if its install steps drift from the new quickstart. - Updating the Coder Quickstart template's description in `coder/registry` if it links to the renamed section. </details> This pull request was generated by a Coder agent on behalf of @nickvigilante. (cherry picked from commit 9d85eb2)
nickvigilante
approved these changes
Jun 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport of #26106
Original PR: #26106 — docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop
Merge commit: 9d85eb2
Requested by: @nickvigilante