mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs(docs/tutorials/quickstart.md): recommend free container runtimes 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.
This commit is contained in:
Nick Vigilante
@@ -35,15 +35,23 @@ explained through a cooking analogy:
|
||||
- 10 minutes of your time
|
||||
|
||||
> [!TIP]
|
||||
> If you use a coding agent like Claude Code, the [coder/skills](https://github.com/coder/skills) `setup` skill can train the coding agent on the following steps (install Docker, install Coder, create your first template, and launch a workspace).
|
||||
> If you use a coding agent like Claude Code, the [coder/skills](https://github.com/coder/skills) `setup` skill can train the coding agent on the following steps (install a container runtime, install Coder, create your first template, and launch a workspace).
|
||||
|
||||
## Step 1: Install Docker and set up permissions
|
||||
## Step 1: Install a container runtime
|
||||
|
||||
Coder needs a Docker-compatible container runtime running on the host, such as
|
||||
[Colima](https://colima.run), [Rancher Desktop](https://rancherdesktop.io),
|
||||
[Podman](https://podman.io), or
|
||||
[Docker Desktop](https://www.docker.com/products/docker-desktop/). If you
|
||||
already have one installed and running, skip ahead to
|
||||
[Step 2](#step-2-install-and-start-coder). Otherwise, follow the steps below to
|
||||
install a free runtime quickly on your platform.
|
||||
|
||||
<div class="tabs">
|
||||
|
||||
### Linux
|
||||
|
||||
1. Install Docker:
|
||||
1. Install Docker Engine:
|
||||
|
||||
```bash
|
||||
curl -sSL https://get.docker.com | sh
|
||||
@@ -74,15 +82,23 @@ explained through a cooking analogy:
|
||||
|
||||
### macOS
|
||||
|
||||
1. [Install Docker](https://docs.docker.com/desktop/setup/install/mac-install/).
|
||||
There is a Homebrew formula for the Docker command and a Homebrew cask of Docker
|
||||
Desktop if you prefer:
|
||||
[Colima](https://colima.run) is a free, lightweight container runtime that
|
||||
provides the Docker daemon on macOS without the overhead of Docker Desktop.
|
||||
|
||||
1. Install Colima and the Docker CLI with [Homebrew](https://brew.sh):
|
||||
|
||||
```shell
|
||||
brew install --cask docker-desktop
|
||||
brew install colima docker
|
||||
```
|
||||
|
||||
1. Open Docker Desktop.
|
||||
1. Start Colima to launch the Docker daemon:
|
||||
|
||||
```shell
|
||||
colima start
|
||||
```
|
||||
|
||||
Colima exposes the Docker socket at `/var/run/docker.sock`, so the Coder
|
||||
Quickstart template works without additional configuration.
|
||||
|
||||
### Windows
|
||||
|
||||
@@ -90,9 +106,32 @@ If you plan to use the built-in PostgreSQL database, ensure that the
|
||||
[Visual C++ Runtime](https://learn.microsoft.com/en-US/cpp/windows/latest-supported-vc-redist#latest-microsoft-visual-c-redistributable-version)
|
||||
is installed.
|
||||
|
||||
1. [Install Docker](https://docs.docker.com/desktop/install/windows-install/).
|
||||
[Podman Desktop](https://podman-desktop.io) is a free GUI for the Podman container runtime.
|
||||
Its onboarding installs and configures the required
|
||||
Windows Subsystem for Linux (WSL2) or Hyper-V layer if it isn't already enabled.
|
||||
|
||||
1. Open Docker Desktop.
|
||||
1. Download and install [Podman Desktop](https://podman-desktop.io/downloads).
|
||||
|
||||
1. Follow the onboarding to configure Podman.
|
||||
|
||||
1. If you configured Podman to use WSL2, then you will need to do either
|
||||
upgrade WSL2 to version 2.5.1 or later
|
||||
(which uses [cgroups](https://wikipedia.org/wiki/Cgroups) v2 by default)
|
||||
or create a `.wslconfig` file in the `%USERPROFILE%` directory
|
||||
with the following contents
|
||||
|
||||
```text
|
||||
[wsl2]
|
||||
kernelCommandLine=cgroup_no_v1=all
|
||||
```
|
||||
|
||||
This is not required for Podman with Hyper-V.
|
||||
|
||||
1. Open Podman Desktop and complete the onboarding to create and start a
|
||||
Podman machine.
|
||||
|
||||
Podman Desktop enables Docker socket compatibility by default, so tools
|
||||
that expect the Docker daemon work without additional configuration.
|
||||
|
||||
</div>
|
||||
|
||||
@@ -275,23 +314,31 @@ When creating a workspace from a Docker template, you may see an error like:
|
||||
Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?
|
||||
```
|
||||
|
||||
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.
|
||||
This means a container runtime is either not installed or not running on the
|
||||
machine where Coder is running. A runtime 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:
|
||||
1. If Colima is not installed, install it with [Homebrew](https://brew.sh):
|
||||
|
||||
```shell
|
||||
brew install --cask docker-desktop
|
||||
brew install colima docker
|
||||
```
|
||||
|
||||
1. Open Docker Desktop and verify that it is running.
|
||||
1. Start Colima to launch the Docker daemon:
|
||||
|
||||
```shell
|
||||
colima start
|
||||
```
|
||||
|
||||
1. Verify that the daemon is reachable:
|
||||
|
||||
```shell
|
||||
docker ps
|
||||
```
|
||||
|
||||
#### Linux
|
||||
|
||||
@@ -324,10 +371,10 @@ Docker-based template.
|
||||
|
||||
#### Windows
|
||||
|
||||
1. If Docker Desktop is not installed,
|
||||
[install it](https://docs.docker.com/desktop/install/windows-install/).
|
||||
1. If Podman Desktop is not installed,
|
||||
[download and install it](https://podman-desktop.io/downloads).
|
||||
|
||||
1. Open Docker Desktop and verify that it is running.
|
||||
1. Open Podman Desktop and verify that a Podman machine is running.
|
||||
|
||||
</div>
|
||||
|
||||
|
||||
Reference in New Issue
Block a user