docs: add top-level Get started section and move the Quickstart (#26821)

Add a top-level "Get started" docs section to the nav and move the Quickstart to /docs/get-started, with inbound link updates and the install page TIP pointing to the Quickstart. Filed via Coder Agents on Nick's behalf.
2026-09-01 14:53:15 +08:00 · 2026-06-29 16:07:10 -04:00
parent c35f3d51eb
commit 89b0a66079
8 changed files with 93 additions and 52 deletions
@@ -184,4 +184,4 @@ See the [templates documentation](./admin/templates/index.md) for details.
 - [Coder Agents](./ai-coder/agents/index.md)
 - [Templates](./admin/templates/index.md)
 - [Installing Coder](./install/index.md)
- [Quickstart tutorial](./tutorials/quickstart.md)
+- [Quickstart tutorial](./get-started/index.md)
@@ -1,7 +1,7 @@
 # Working with templates

 You create and edit Coder templates as
-[Terraform](../../../tutorials/quickstart.md) configuration files (`.tf`) and
+[Terraform](https://developer.hashicorp.com/terraform/intro) configuration files (`.tf`) and
 any supporting files, like a README or configuration files for other services.

 ## Who creates templates?
@@ -24,7 +24,7 @@ This guide walks you through how to configure GitHub and Coder together so that

 The below steps outline how to use the Coder [Create Task Action GHA](https://github.com/coder/create-task-action) in a GitHub workflow to solve a bug. The guide makes the following assumptions:

- You have access to a Coder Server that is running. If you don't have a Coder Server running, follow our [Quickstart Guide](https://coder.com/docs/tutorials/quickstart)
+- You have access to a Coder Server that is running. If you don't have a Coder Server running, follow our [Get started guide](../get-started/index.md)
 - Your Coder Server is accessible from GitHub
 - You have an AI-enabled Task Template that can successfully create a Coder Task. If you don't have a Task Template available, follow our [Getting Started with Tasks Guide](https://coder.com/docs/ai-coder/tasks#getting-started-with-tasks)
 - Check the [Requirements section of the GHA](https://github.com/coder/create-task-action?tab=readme-ov-file#requirements) for specific version requirements for your Coder deployment and the following
@@ -53,7 +53,7 @@ install a free runtime quickly on your platform.

 1. Install Docker Engine:

-   ```bash
+   ```sh
   curl -sSL https://get.docker.com | sh
   ```

@@ -61,13 +61,13 @@ install a free runtime quickly on your platform.

 1. Assign your user to the Docker group:

-   ```shell
+   ```sh
   sudo usermod -aG docker $USER
   ```

 1. Run `newgrp` to activate the groups changes:

-   ```shell
+   ```sh
   newgrp docker
   ```

@@ -76,7 +76,7 @@ install a free runtime quickly on your platform.

 1. Launch the Docker daemon:

-   ```shell
+   ```sh
   sudo systemctl start docker
   ```

@@ -87,18 +87,25 @@ 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
+   ```sh
   brew install colima docker
   ```

 1. Start Colima to launch the Docker daemon:

-   ```shell
+   ```sh
   colima start
   ```

-   Colima exposes the Docker socket at `/var/run/docker.sock`, so the Coder
-   Quickstart template works without additional configuration.
+1. Point `DOCKER_HOST` at the Colima socket so Coder can reach the daemon:
+
+   ```sh
+   export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
+   ```
+
+   Colima exposes its Docker socket at `~/.colima/default/docker.sock`, not `/var/run/docker.sock`, so Coder needs `DOCKER_HOST` to find it.
+   Set it in the same terminal where you'll run `coder server` in the next step.
+   To persist it across new terminals and restarts, add the `export` line to your shell's startup file, such as `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`.

 ### Windows

@@ -145,7 +152,7 @@ Install the `coder` CLI to get started:

 1. Install Coder:

-   ```shell
+   ```sh
   curl -L https://coder.com/install.sh | sh
   ```

@@ -155,7 +162,7 @@ Install the `coder` CLI to get started:

 1. Start Coder:

-   ```shell
+   ```sh
   coder server
   ```

@@ -175,7 +182,7 @@ is installed.

 1. Start Coder:

-   ```shell
+   ```sh
   coder server
   ```

@@ -216,19 +223,32 @@ Templates define what's in your development environment. The following is a basi

   **Note:** running this template requires Docker to be running in the background, so make sure Docker is running!

-3. Name your template:
-   - Name: `quickstart`
-   - Display name: `quickstart doc template`
-   - Description: `Provision Docker containers as Coder workspaces`
+3. Name your template.
+   The **Display name** and **Description** are pre-filled from the starter template, so you can keep the defaults or replace them:
+   - **Name**: `quickstart`
+   - **Display name**: `Coder Quickstart`
+   - **Description**: `Get started with Coder by picking your languages, editors, and a repo`

 4. Select **Save**.

   ![Create template](../images/screenshots/create-template.png)

-**What just happened?** You defined a template — a reusable blueprint for dev
-environments — in your Coder deployment. It's now stored in your organization's
-template list, where you and any teammates in the same org can create workspaces
-from it. Now it's time launch a workspace.
+**What just happened?**
+You defined a template, a reusable blueprint for dev environments, in your Coder deployment.
+It's now stored in your organization's template list, where you and any teammates in the same organization can create workspaces from it.
+
+<details>
+<summary>What happens under the hood?</summary>
+
+A Coder template is a [Terraform](https://developer.hashicorp.com/terraform/intro) configuration, and Coder is built on top of Terraform.
+When you create a workspace from this template, a Coder [provisioner](../admin/infrastructure/architecture.md#provisionerd) runs a Terraform job from the template's configuration to build your environment.
+For the Coder Quickstart template, that job starts a Docker container, connects the Coder agent, and runs a startup script that installs the programming languages and editors you choose in the next step.
+
+To learn how Coder uses Terraform to provision and run workspaces, refer to the [architecture overview](../admin/infrastructure/architecture.md).
+
+</details>
+
+Now it's time to launch a workspace.

 ## Step 5: Launch your workspace

@@ -252,10 +272,13 @@ After a short wait (10-15 seconds on most modern computers), Coder will start yo

 ## Step 6: Connect your IDE

-Each of the buttons in the workspace view is a different **agent app**
-(more on this in a later section). Select your preferred IDE from the
-list of agent apps. This guide assumes you'll use Visual Studio Code,
-but the process is similar for other IDEs and editors.
+Each button in the workspace view is a different **agent app**.
+The buttons you see reflect the editors you selected in the **IDEs & Editors** parameter in [Step 5](#step-5-launch-your-workspace).
+Select your preferred IDE from the list of agent apps.
+
+This guide uses **VS Code Desktop**, which opens the workspace in the VS Code installed on your local machine, using the Coder extension.
+To stay in the browser instead, select the browser-based VS Code option.
+The remaining steps are similar for other IDEs and editors.

 After VS Code loads the remote environment, you can select **Open Folder** to
 explore directories in the Docker container or work on something new.
@@ -314,9 +337,12 @@ 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 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.
+This usually 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.
+
+If the runtime is running but Coder still cannot connect, the daemon may expose its socket at a path other than `/var/run/docker.sock`.
+This is common with Colima on macOS and with rootless Docker on Linux.
+In that case, point Coder at the socket with the `DOCKER_HOST` environment variable, then restart the Coder server.

 <div class="tabs">

@@ -324,40 +350,48 @@ workspace from a Docker-based template.

 1. If Colima is not installed, install it with [Homebrew](https://brew.sh):

-   ```shell
+   ```sh
   brew install colima docker
   ```

 1. Start Colima to launch the Docker daemon:

-   ```shell
+   ```sh
   colima start
   ```

 1. Verify that the daemon is reachable:

-   ```shell
+   ```sh
   docker ps
   ```

+1. If `docker ps` works but Coder still cannot connect, point `DOCKER_HOST` at the Colima socket, then restart the Coder server:
+
+   ```sh
+   export DOCKER_HOST="unix://${HOME}/.colima/default/docker.sock"
+   ```
+
+   To persist the setting across restarts, add that `export` line to your shell's startup file, such as `~/.zshrc`, `~/.bashrc`, or `~/.config/fish/config.fish`.
+
 #### Linux

 1. Install Docker, if you haven't already:

-   ```shell
+   ```sh
   curl -sSL https://get.docker.com | sh
   ```

 1. Start the Docker daemon:

-   ```shell
+   ```sh
   sudo systemctl start docker
   ```

 1. Assign your user to the `docker` group so Coder can access the daemon
   without root:

-   ```shell
+   ```sh
   sudo usermod -aG docker $USER
   newgrp docker
   ```
@@ -380,7 +414,7 @@ workspace from a Docker-based template.

 ### Can't start Coder server: Address already in use

-```shell
+```text
 Encountered an error running "coder server", see "coder server --help" for more information
 error: configure http(s): listen tcp 127.0.0.1:3000: bind: address already in use
 ```
@@ -392,13 +426,13 @@ then start the server again.

 1. Stop the process:

-   ```shell
+   ```sh
   sudo systemctl stop coder
   ```

 1. Start Coder:

-   ```shell
+   ```sh
   coder server
   ```

@@ -406,25 +440,25 @@ then start the server again.

 1. Identify the process using port 3000:

-   ```shell
+   ```sh
   lsof -i :3000
   ```

 1. Stop the process using the PID from the previous command:

-   ```shell
+   ```sh
   kill <PID>
   ```

   If the process does not exit, force-kill it:

-   ```shell
+   ```sh
   kill -9 <PID>
   ```

 1. Start Coder:

-   ```shell
+   ```sh
   coder server
   ```

@@ -444,6 +478,6 @@ then start the server again.

 1. Start Coder:

-   ```shell
+   ```sh
   coder server
   ```
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="feather feather-rocket" viewBox="0 0 24 24">
+  <path d="M4.5 16.5c-1.5 1.26-2 5-2 5s3.74-.5 5-2c.71-.84.7-2.13-.09-2.91a2.18 2.18 0 0 0-2.91-.09z"/>
+  <path d="m12 15-3-3a22 22 0 0 1 2-3.95A12.88 12.88 0 0 1 22 2c0 2.72-.78 7.5-6 11a22.35 22.35 0 0 1-4 2z"/>
+  <path d="M9 12H4s.55-3.03 2-4c1.62-1.08 5 0 5 0"/>
+  <path d="M12 15v5s3.03-.55 4-2c1.08-1.62 0-5 0-5"/>
+</svg>
@@ -111,7 +111,7 @@ Error: Error pinging Docker server: Cannot connect to the Docker daemon at unix:

 Docker is not installed or not running on the host. Install Docker and start the
 daemon before creating a workspace from a Docker-based template. Refer to the
-[quickstart troubleshooting](../tutorials/quickstart.md#cannot-connect-to-the-docker-daemon)
+[Troubleshooting section of the get started guide](../get-started/index.md#cannot-connect-to-the-docker-daemon)
 for platform-specific steps.

 ### Docker-based workspace is stuck in "Connecting..."
@@ -8,10 +8,10 @@ We support two release channels: mainline and stable - read the
 There are several ways to install Coder. Follow the steps on this page for a
 minimal installation of Coder, or for a step-by-step guide on how to install and
 configure your first Coder deployment, follow the
-[quickstart guide](../tutorials/quickstart.md).
+[quickstart guide](../get-started/index.md).

 > [!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 to install and bootstrap a Coder deployment end-to-end.
+> If you're installing Coder for the first time, the [Quickstart](../get-started/index.md) guides you through installing Coder and launching your first workspace.

 ## Local/Individual Installs

@@ -12,11 +12,6 @@
 					"description": "View screenshots of the Coder platform",
 					"path": "./about/screenshots.md"
 				},
-				{
-					"title": "Quickstart",
-					"description": "Learn how to install and run Coder quickly",
-					"path": "./tutorials/quickstart.md"
-				},
 				{
 					"title": "Support",
 					"description": "How Coder supports your deployment and you",
@@ -87,6 +82,12 @@
 				}
 			]
 		},
+		{
+			"title": "Get started",
+			"description": "Install Coder and launch your first workspace",
+			"path": "./get-started/index.md",
+			"icon_path": "./images/icons/rocket.svg"
+		},
 		{
 			"title": "Install",
 			"description": "Installing Coder",
@@ -1362,7 +1363,7 @@
 				{
 					"title": "Quickstart",
 					"description": "Learn how to install and run Coder quickly",
-					"path": "./tutorials/quickstart.md"
+					"path": "./get-started/index.md"
 				},
 				{
 					"title": "Write a Template from Scratch",