mirror of https://github.com/coder/coder.git synced 2026-09-22 05:05:20 +08:00

Files

T

Jeremy Ruppel 79fc8541ed docs: update template creation docs for template builder (#26993 )

## Summary

Update documentation across 9 files to present the template builder as
the primary template creation method, replacing the old starter
templates flow as the default entry point.

The template builder is a guided wizard that lets admins select base
infrastructure, add registry modules, configure variables, and produce
validated Terraform without writing HCL.

## Changes

**Primary docs (significant rewrites):**
- `docs/admin/templates/creating-templates.md`: Added "Using the
template builder" as the first section with full 5-step wizard
documentation, screenshots, airgap/registry notes, and alternative
creation links. Moved CLI starter template flow to its own section.
Fixed "You can the" typo.
- `docs/get-started/index.md`: Rewrote Steps 4-6 to use the builder with
the Docker base template instead of the Coder Quickstart (which is not a
builder base template). Generalized workspace parameter instructions.
- `docs/start/first-template.md`: Rewrote to use the builder. Removed
old starter templates references, TODO notes, typo, and commented-out
sections.

**Secondary docs (targeted edits):**
- `docs/admin/templates/index.md`: Replaced starter templates section
with builder-first "Create a template" section.
- `docs/admin/templates/managing-templates/index.md`: Renamed "Starter
templates" to "Creating templates" pointing to the builder.
- `docs/install/airgap.md`: Added "Template builder" section documenting
`CODER_DISABLE_TEMPLATE_BUILDER` and
`CODER_TEMPLATE_BUILDER_REGISTRY_URL`.
- `docs/tutorials/template-from-scratch.md`: Added TIP callout
recommending the builder. Fixed `coder templates create` -> `coder
templates push` inconsistency.
- `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`:
Updated Dashboard tab to reference the builder and "Upload an existing
template" alternative.
- `docs/about/screenshots.md`: Updated caption and image reference for
template builder.

**Screenshots added:**
- `templatebuilder_01_bases.png` (base selection step)
- `templatebuilder_02_modules.png` (module selection step)
- `templatebuilder_03_module_customization.png` (module settings step)
- `templatebuilder_04_customizations.png` (template customizations step)

<details>
<summary>Implementation plan</summary>

# Plan: Update docs/ for Template Builder Launch

## Summary

The Template Builder is a new guided wizard at `/templates/new/builder`
that lets admins create templates by selecting a base infrastructure
template, composing it with registry modules, configuring variables, and
producing a validated Terraform bundle without writing HCL. The docs
need to be updated to present this as the primary/recommended template
creation path, while preserving the existing paths (upload, CLI,
duplicate) as alternatives.

## Key behavioral facts from the code

- **Route**: `/templates/new/builder` (new), `/templates/new` (old,
still exists)
- **Entry point**: The "New Template" button on the Templates page links
to `/templates/new/builder` when the builder is enabled; otherwise falls
back to `/starter-templates`
- **5-step wizard**:
  1. **Select base infrastructure** (e.g., Docker, AWS EC2, Kubernetes)
  2. **Base template parameters** (optional, skipped if base has none)
3. **Select modules** (IDE, AI Agent, Source Control, etc.;
multi-select, grouped by category)
4. **Module settings** (optional, skipped if no configurable variables)
5. **Template customizations** (name, display name, description, icon,
organization)
- **Alternative creation links** are shown on step 1: "Start from
scratch", "Upload an existing template", "Browse community templates",
"Use template agent skill"
- **Disabled via**: `CODER_DISABLE_TEMPLATE_BUILDER` env var /
`--disable-template-builder` flag. When disabled, redirects to old
`/templates/new` flow
- **Registry URL override**: `CODER_TEMPLATE_BUILDER_REGISTRY_URL`
(default: `registry.coder.com`)
- **Requires outbound access** to `registry.coder.com` for `terraform
init` at compose time
- **Modules are bundled** with the Coder release binary; the builder
does not fetch metadata from the registry at runtime
- **Sensitive variables** (secrets) are not collected by the builder;
they are deferred to workspace creation time
- **Module conflicts** show a warning but do not block creation
- **One-way**: No re-entry into the builder for existing templates; edit
HCL directly after creation

## Files to update

### Tier 1: Primary creation flow docs (significant rewrites)

#### 1. `docs/admin/templates/creating-templates.md`

**Current state**: Documents three creation paths: "From a starter
template" (primary), "From an existing template", "From scratch
(advanced)".

**Changes**:
- Add a new section **"Using the template builder"** as the first and
primary section (before "From a starter template").
- Describe the 5-step wizard flow: select base infrastructure, configure
base parameters, select modules, configure module settings, set template
customizations.
- Mention that the builder is enabled by default and requires outbound
access to `registry.coder.com`.
- Note that sensitive variables are collected from developers at
workspace creation, not during template building.
- Add a callout about disabling the builder for airgapped deployments
(`CODER_DISABLE_TEMPLATE_BUILDER`).
- Note the `CODER_TEMPLATE_BUILDER_REGISTRY_URL` option for self-hosted
registry mirrors.
- Keep existing "From a starter template", "From an existing template",
and "From scratch" sections largely intact, but reframe them as
alternative paths.
- Update the "From a starter template" Web UI instructions to note the
new entry point routing (the "New Template" button now goes to the
builder when enabled).
- Fix existing typo: "You can the [Coder CLI]" should be "You can use
the [Coder CLI]".

#### 2. `docs/start/first-template.md`

**Current state**: Beginner tutorial walking through creating a template
from the Docker starter template via the old flow. Has a typo (`s` at
end of line 32), commented-out workspace creation section, and TODO
notes.

**Changes**:
- Rewrite steps 2 and 3 to use the Template Builder as the primary path.
- Step 2: Navigate to **Templates**, select **New Template**, which
opens the Template Builder.
- Step 3: Walk through the builder wizard steps (select Docker base,
optionally select modules like code-server, configure template
name/description, create).
- Remove the typo on line 32 (`s`).
- Keep the "Modify your template" section (step 6) intact since it
covers post-creation editing which is unchanged.
- Remove or update the reference to "Starter Templates" as a separate
page since the builder subsumes that entry point.

#### 3. `docs/get-started/index.md`

**Current state**: Quickstart guide. Step 4 says "Select **Templates** →
**New Template**" then pick "Coder Quickstart" from starter templates.

**Changes**:
- Update Step 4 to describe using the Template Builder.
- The flow becomes: Select **Templates** → **New Template** → builder
opens → select **Coder Quickstart** as the base template → optionally
add modules → set name/description → **Create Template**.
- Update the "What just happened?" explanation to mention the builder
composed and validated the Terraform.
- Screenshot reference `create-quickstart-template.png` will need a new
screenshot (note this in the PR; screenshots are out of scope for this
change but should be flagged).

### Tier 2: Secondary references (targeted edits)

#### 4. `docs/admin/templates/index.md`

**Current state**: Overview page mentioning starter templates as the
primary creation path.

**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the recommended way to create templates, with starter templates
serving as base templates within the builder.
- Update the link to point to the builder section: `[Create a template
with the template
builder](./creating-templates.md#using-the-template-builder)`.
- Update the screenshot reference and caption. The "Starter Templates"
page screenshot may no longer be the first thing admins see.

#### 5. `docs/admin/templates/managing-templates/index.md`

**Current state**: Documents starter templates, editing, updating,
deleting.

**Changes**:
- Update the "Starter templates" section to mention the Template Builder
as the primary creation path, with starter templates available as base
templates within it.
- Update the image reference from `starter-templates.png` if it shows
the old flow.

#### 6. `docs/tutorials/template-from-scratch.md`

**Current state**: Detailed tutorial for writing a template from scratch
with Terraform.

**Changes**:
- Add a brief note at the top recommending the Template Builder for
users who want to create templates without writing Terraform, with a
link to
`docs/admin/templates/creating-templates.md#using-the-template-builder`.
- In section "7. Create the template in Coder" → "Dashboard" tab, update
the UI steps. The "Upload template" option is now accessed via the old
creation flow at `/templates/new` (or through the "Upload an existing
template" link in the builder's alternatives).
- Fix the inconsistency where text says `coder templates create` but the
code block uses `coder templates push`.

#### 7.
`docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`

**Current state**: Documents creating envbuilder templates via
Dashboard, CLI, and Registry tabs.

**Changes**:
- In the Dashboard tab, update the instructions. The "Create Template"
button now opens the builder by default. Users need to use the "Upload
an existing template" alternative link or navigate to `/templates/new`
directly.
- Update "From scratch" reference since that option is now an
alternative link in the builder.
- The CLI and Registry tabs remain unchanged.

#### 8. `docs/install/airgap.md`

**Current state**: Documents air-gapped installations. No mention of
Template Builder.

**Changes**:
- Add a note in the relevant section about the Template Builder
requiring outbound access to `registry.coder.com`.
- Document `CODER_DISABLE_TEMPLATE_BUILDER` for fully air-gapped
deployments.
- Document `CODER_TEMPLATE_BUILDER_REGISTRY_URL` for deployments using a
self-hosted registry mirror.

#### 9. `docs/about/screenshots.md`

**Current state**: Contains a caption "Template administrators can
either create a new Template from scratch or choose a Starter Template".

**Changes**:
- Update the caption to mention the Template Builder as the primary
creation method.
- Screenshot reference may need updating (flag for new screenshot).

### Tier 3: Minor/link-only updates

#### 10. `docs/admin/users/organizations.md`

- If it references the old "Create Template" screen with an org picker,
add a note that the Template Builder also includes organization
selection in its final step.

#### 11. `docs/ai-coder/tasks.md`

- If it mentions creating templates, add a passing reference to the
Template Builder as an option.

## Files NOT to update

- `docs/reference/api/templatebuilder.md`: Auto-generated API reference.
Already correct.
- `docs/reference/api/schemas.md`: Auto-generated. Already correct.
- `docs/reference/cli/server.md`: Auto-generated. Already has
`--disable-template-builder` and `--template-builder-registry-url`.
- `docs/reference/cli/templates_create.md`: Already deprecated.
- `docs/reference/cli/templates.md`: No changes needed.

## Implementation order

1. `docs/admin/templates/creating-templates.md` (primary creation docs,
most content)
2. `docs/get-started/index.md` (quickstart)
3. `docs/start/first-template.md` (beginner tutorial)
4. `docs/admin/templates/index.md` (overview)
5. `docs/admin/templates/managing-templates/index.md` (managing
overview)
6. `docs/install/airgap.md` (airgap note)
7. `docs/tutorials/template-from-scratch.md` (from-scratch tutorial)
8. `docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md`
(envbuilder)
9. `docs/about/screenshots.md` (screenshot captions)
10. Minor link/reference updates in tier 3 files

## Style notes

- Follow the Diataxis framework; keep tutorials as tutorials, reference
as reference.
- Use present tense, active voice, second person.
- Bold for UI elements: **Templates**, **New Template**, **Create
Template**.
- No emdash/endash.
- Do not add screenshots; flag where new screenshots are needed as
comments/TODOs.
- Run `make fmt/markdown` and `make lint/markdown` after all changes.
- Verify all pages are already in `docs/manifest.json` (no new pages
being added, only existing pages being updated).

</details>

> 🤖 Generated by Coder Agents

2026-07-06 11:15:59 -04:00

16 KiB

Raw Blame History

Quickstart

Follow this guide to get your first Coder development environment running in under 10 minutes. This guide covers the essential concepts and shows you how to create your first workspace and open it in your preferred editor. This workspace includes a basic set of tools to edit most code bases.

What you'll do

In this quickstart, you'll:

✅ Install Coder server.
✅ Create a template (blueprint for dev environments).
✅ Launch a workspace (your actual dev environment).
✅ Connect from your favorite IDE.

A 30-second metaphor for Coder

Before diving in, the following table breaks down the core concepts that power Coder, explained through a cooking analogy:

Component	What It Is	Real-World Analogy
You	The engineer/developer/builder working	The head chef cooking the meal
Templates	A Terraform blueprint that defines your dev environment (OS, tools, resources)	Recipe for a meal
Workspaces	The actual running environment created from the template	The cooked meal
Users	A developer who launches the workspace from a template and does their work inside it	The people eating the meal

Putting it Together: Coder separates who defines environments from who uses them. Admins create and manage Templates, the recipes, while developers use those Templates to launch Workspaces, the meals.

Prerequisites

A machine with 2+ CPU cores and 4GB+ RAM
Familiarity with running commands in the terminal
10 minutes of your time

Tip

If you use a coding agent like Claude Code, the 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 a container runtime

Coder needs a Docker-compatible container runtime running on the host, such as Colima, Rancher Desktop, Podman, or Docker Desktop. If you already have one installed and running, skip ahead to Step 2. Otherwise, follow the steps below to install a free runtime quickly on your platform.

Linux

Install Docker Engine:
```
curl -sSL https://get.docker.com | sh
```
For more details, visit Docker's docs on installing Docker on Linux.
Assign your user to the Docker group:
```
sudo usermod -aG docker $USER
```
Run newgrp to activate the groups changes:
```
newgrp docker
```
You might need to log out of and back into your machine or restart your machine for changes to take effect.
Launch the Docker daemon:
```
sudo systemctl start docker
```

macOS

Colima is a free, lightweight container runtime that provides the Docker daemon on macOS without the overhead of Docker Desktop.

Install Colima and the Docker CLI with Homebrew:
```
brew install colima docker
```
Start Colima to launch the Docker daemon:
```
colima start
```
Point DOCKER_HOST at the Colima socket so Coder can reach the daemon:
```
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

If you plan to use the built-in PostgreSQL database, ensure that the Visual C++ Runtime is installed.

Podman Desktop 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.

Download and install Podman Desktop.
Follow the onboarding to configure Podman.
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 v2 by default) or create a .wslconfig file in the %USERPROFILE% directory with the following contents
```
[wsl2]
kernelCommandLine=cgroup_no_v1=all
```
This is not required for Podman with Hyper-V.
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.

Step 2: Install and start Coder

Install the coder CLI to get started:

Linux/macOS

Install Coder:
```
curl -L https://coder.com/install.sh | sh
```
- For standalone binaries, system packages, or other alternate installation methods, refer to the latest release on GitHub.
Start Coder:
```
coder server
```

Windows

If you plan to use the built-in PostgreSQL database, ensure that the Visual C++ Runtime is installed.

Use the winget package manager to install Coder:
```
winget install Coder.Coder
```
Start Coder:
```
coder server
```

Coder will attempt to open the setup page in your browser. If it doesn't open automatically, go to http://localhost:3000.

If you get a browser warning similar to Secure Site Not Available, you can ignore the warning and continue to the setup page.

If your Coder server is on a network or cloud device, or you are having trouble viewing the page, locate the web UI URL in Coder logs in your terminal. It looks like https://<CUSTOM-STRING>.<TUNNEL>.try.coder.app. It's one of the first lines of output, so you might have to scroll up to find it.

Step 3: Initial setup

Create your admin account:
- Email: your.email@example.com
- Password: Choose a strong password.
You can also choose to Continue with GitHub instead of creating an admin account. Coder automatically grants admin permissions to the first user that signs in.

Step 4: Create your first template and workspace

Tip

If you use an AI coding assistant, the coder-templates agent skill can guide you through creating and customizing templates with best practices built-in.

Templates define what's in your development environment. The template builder guides you through creating one without writing any Terraform.

Select Templates > New Template. The template builder opens.
Select the Docker base template from the list.

Note

This template requires Docker to be running in the background, so make sure Docker is running.
Skip or configure any base template parameters, then select modules to add IDEs and tools to your template. For example, add code-server to get VS Code in the browser. You can skip module selection for now and add modules later.
On the final step, name your template:
- Name: my-docker-template
- Display name and Description: fill in as you like.
Select Create Template. Coder composes and validates the Terraform configuration, then creates your template.

What just happened? The template builder selected a base infrastructure template, composed it with any modules you chose, and generated a valid Terraform configuration. Coder validated the configuration server-side, then created a reusable template in your organization's template list. You and any teammates in the same organization can now create workspaces from it.

What happens under the hood?

A Coder template is a Terraform configuration, and Coder is built on top of Terraform. When you create a workspace from this template, a Coder provisioner runs a Terraform job from the template's configuration to build your environment. For the Docker base template, that job starts a Docker container with the Coder agent pre-configured, along with any modules you selected.

To learn how Coder uses Terraform to provision and run workspaces, refer to the architecture overview.

Now it's time to launch a workspace.

Step 5: Launch your workspace

After the template is ready, select + Create Workspace.
Give the workspace a name. If you need a suggestion, you can select the automatically generated name next to the Need a suggestion? label.
If the template has any parameters, fill them in. Parameters vary by template and the modules you selected in the builder.
Select Create workspace.

After a short wait (10-15 seconds on most modern computers), Coder will start your new workspace:

Workspace is running

Step 6: Connect your IDE

Each button in the workspace view is a different agent app. The buttons in the UI reflect the modules you added in the template builder (such as code-server, Claude Code, or any of the JetBrains editors). 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.

If you didn't clone an existing Git repository when you created your workspace, you can clone it manually if you want:

Select Clone Repository and enter the repository URL.

For example, to clone the Coder repo, enter https://github.com/coder/coder.git.

Learn more about how to find the repository URL in the GitHub documentation.
Choose the folder to which VS Code should clone the repo. It will be in its own directory within this folder.

Note that you cannot create a new parent directory in this step.
After VS Code completes the clone, select Open to open the directory.
You are now using VS Code in your Coder environment!

What's next?

You now have:

A Coder server running locally.
A template defining your environment.
A workspace running that environment.
IDE access to code remotely.

Now that you have your own workspace running, you can customize your template to fit your needs.

Learn more

Try Coder Agents, the chat interface and API for delegating development work to coding agents in your Coder deployment.
Read about managing Workspaces for your team
Read about implementing monitoring tools for your Coder Deployment

Troubleshooting

Cannot connect to the Docker daemon

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 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.

Linux

Install Docker, if you haven't already:
```
curl -sSL https://get.docker.com | sh
```
Start the Docker daemon:
```
sudo systemctl start docker
```
Assign your user to the docker group so Coder can access the daemon without root:
```
sudo usermod -aG docker $USER
newgrp docker
```
Confirm the group membership:
```
$ groups
docker sudo users
```

macOS

If Colima is not installed, install it with Homebrew:
```
brew install colima docker
```
Start Colima to launch the Docker daemon:
```
colima start
```
Verify that the daemon is reachable:
```
docker ps
```
If docker ps works but Coder still cannot connect, point DOCKER_HOST at the Colima socket, then restart the Coder server:
```
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.

Windows

If Podman Desktop is not installed, download and install it.
Open Podman Desktop and verify that a Podman machine is running.

Can't start Coder server: Address already in use

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

Another process is already listening on port 3000. Identify and stop it, then start the server again.

Linux

Stop the process:
```
sudo systemctl stop coder
```
Start Coder:
```
coder server
```

macOS

Identify the process using port 3000:
```
lsof -i :3000
```
Stop the process using the PID from the previous command:
```
kill <PID>
```
If the process does not exit, force-kill it:
```
kill -9 <PID>
```
Start Coder:
```
coder server
```

Windows

Identify the process using port 3000 in PowerShell:

Get-NetTCPConnection -LocalPort 3000 | Select-Object OwningProcess

Stop the process using the PID from the previous command:
```
Stop-Process -Id <PID>
```
Start Coder:
```
coder server
```

16 KiB Raw Blame History

Quickstart

What you'll do

A 30-second metaphor for Coder

Prerequisites

Step 1: Install a container runtime

Linux

macOS

Windows

Step 2: Install and start Coder

Linux/macOS

Windows

Step 3: Initial setup

Step 4: Create your first template and workspace

Step 5: Launch your workspace

Step 6: Connect your IDE

What's next?

Learn more

Troubleshooting

Cannot connect to the Docker daemon

Linux

macOS

Windows

Can't start Coder server: Address already in use

Linux

macOS

Windows

16 KiB

Raw Blame History