Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
nickvigilante wants to merge 1 commit into
base: main
Choose a base branch
from
+53 −21
Draft

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

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 53 additions & 21 deletions docs/tutorials/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -74,25 +82,41 @@ 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

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.

</div>

Expand Down Expand Up @@ -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.

<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

Expand Down Expand Up @@ -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.

</div>

Expand Down
Loading