docs(docs/tutorials/quickstart.md): recommend free container runtimes besides Docker Desktop#26106
Draft
nickvigilante wants to merge 1 commit into
Conversation
… besides Docker Desktop Replace the 'Install Docker' step with a runtime-agnostic 'Install a container runtime' step. Add a callout above the OS tabs naming Colima, Rancher Desktop, Podman, and Docker Desktop as valid runtimes. Switch the per-platform defaults to free, lightweight options: Docker Engine on Linux, Colima on macOS, Podman Desktop on Windows. Update the troubleshooting subsections to match the new defaults. Linear: DEVREL-22 This commit was generated by a Coder agent on behalf of Nick Vigilante.
Docs preview📖 View docs preview for |
bpmct
approved these changes
Jun 5, 2026
Member
|
Approving given this has been tested! |
Contributor
Author
|
@bpmct I'm going to set up and boot up my gaming PC running Windows this afternoon and check. Doing macOS now. I won't merge until I have confirmed it works on all operating systems. |
Contributor
Author
|
I hit a snag installing Podman on Windows through WSL, but I confirmed it works end-to-end on Windows. I'm going to add a note to the Windows steps that users need to add a |
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
2 participants
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.
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:
The "Cannot connect to the Docker daemon" troubleshooting subsections are
updated to match the new defaults.
Closes DEVREL-22.
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.
Implementation proposal and pre-mortem
DEVREL-22 proposal: Replace "Install Docker" with "Install a container runtime"
Linear: DEVREL-22
Repo:
coder/coderBranch:
vigilante/devrel-22-recommend-orbstackcolimarancher-desktoppodman-as-dockerPrimary file:
docs/tutorials/quickstart.mdSummary
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
Per-platform defaults
curl -sSL https://get.docker.com | shbrew install colima docker,colima start), free for commercial use, exposes/var/run/docker.sockso the Coder template needs zero env vars.podman machinesetup through the GUI, sets up Docker socket compatibility. Lighter than Docker Desktop, simpler than CLI Podman +DOCKER_HOST.Pre-mortem
/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 withoutDOCKER_HOSTgymnastics.quickstart#step-1-install-docker-and-set-up-permissions. A grep ofdocs/andsite/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.brew install colima dockerassumes Homebrew. The callout links to brew.sh so users without it can install Homebrew first.Out of scope (follow-up issues)
docs/install/docker.mdupdates. That page is about installing Coder server in a Docker container, which is a separate concern.coder/skillssetupskill if its install steps drift from the new quickstart.coder/registryif it links to the renamed section.This pull request was generated by a Coder agent on behalf of @nickvigilante.