From 3eb1fd09be78931a2f86d59bab6c5f4f174e21c7 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 5 Jun 2026 17:05:44 +0000 Subject: [PATCH 1/2] docs(docs/tutorials/quickstart.md): recommend free container runtimes 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/tutorials/quickstart.md | 74 ++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 21 deletions(-) diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md index eb231b791961d..44a771ce055bf 100644 --- a/docs/tutorials/quickstart.md +++ b/docs/tutorials/quickstart.md @@ -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.
### 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 colima docker + ``` + +1. Start Colima to launch the Docker daemon: ```shell - brew install --cask docker-desktop + colima start ``` -1. Open Docker Desktop. + Colima exposes the Docker socket at `/var/run/docker.sock`, so the Coder + Quickstart template works without additional configuration. ### Windows @@ -90,9 +106,17 @@ 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 the required Windows Subsystem for +Linux (WSL2) layer if it isn't already enabled. + +1. Download and install [Podman Desktop](https://podman-desktop.io/downloads). + +1. Open Podman Desktop and complete the onboarding to create and start a + Podman machine. -1. Open Docker Desktop. + Podman Desktop enables Docker socket compatibility by default, so tools + that expect the Docker daemon work without additional configuration.
@@ -275,23 +299,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.
#### 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 +356,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.
From 9cd37974e6983319ab94f73b7fc99ff2edd9b6a1 Mon Sep 17 00:00:00 2001 From: Nick Vigilante Date: Fri, 5 Jun 2026 21:55:56 +0000 Subject: [PATCH 2/2] Add note about WSL2 cgroups v2 limitation --- docs/tutorials/quickstart.md | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/docs/tutorials/quickstart.md b/docs/tutorials/quickstart.md index 44a771ce055bf..45a067608c073 100644 --- a/docs/tutorials/quickstart.md +++ b/docs/tutorials/quickstart.md @@ -106,12 +106,27 @@ 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. -[Podman Desktop](https://podman-desktop.io) is a free GUI for the Podman -container runtime. Its onboarding installs the required Windows Subsystem for -Linux (WSL2) layer if it isn't already enabled. +[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. 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.