Skip to content

docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop (#26106)#26120

Merged
nickvigilante merged 1 commit into
release/2.34from
backport/26106-to-2.34
Jun 5, 2026
Merged

docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop (#26106)#26120
nickvigilante merged 1 commit into
release/2.34from
backport/26106-to-2.34

Conversation

@github-actions
Copy link
Copy Markdown

@github-actions github-actions Bot commented Jun 5, 2026

Backport of #26106

Original PR: #26106 — docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop
Merge commit: 9d85eb2
Requested by: @nickvigilante

… 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 nickvigilante merged commit 9443ae0 into release/2.34 Jun 5, 2026
@nickvigilante nickvigilante deleted the backport/26106-to-2.34 branch June 5, 2026 22:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant