opensource/coder
3
0
Fork 0
mirror of https://github.com/coder/coder.git synced 2026-09-24 15:04:27 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: update template creation docs for template builder (#26993)

Browse Source 
## 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
This commit is contained in:
Jeremy Ruppel
2026-07-06 11:15:59 -04:00
committed by GitHub
parent 2cbc464c72
commit 79fc8541ed
21 changed files with 201 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md
+5 -16
View File
@@ -14,22 +14,11 @@ choose a template from the
## Dashboard
1. In the Coder dashboard, select **Templates** then **Create Template**.
1. Use a
[starter template](../../../../../examples/templates)
or create a new template:
- Starter template:
1. Select **Choose a starter template**.
1. Choose a template from the list or select **Devcontainer** from the
sidebar to display only dev container-compatible templates.
1. Select **Use template**, enter the details, then select **Create
template**.
- To create a new template, select **From scratch** and enter the templates
details, then select **Create template**.
1. In the Coder dashboard, select **Templates** > **New Template**.
The template builder opens.
1. The template builder does not currently include dev-container-compatible base templates.
Select **Upload an existing template** at the bottom of the page to upload your Terraform files directly.
1. Upload your `.zip` or `.tar.gz` file, enter the details, then select **Create template**.
1. Edit the template files to fit your deployment.
## CLI
docs/admin/templates/creating-templates.md
+81 -15
View File
@@ -9,28 +9,93 @@ In most cases, it is best to start with a starter template.
<div class="tabs">
### Web UI
### Template builder
After navigating to the Templates page in the Coder dashboard, choose
`Create Template > Choose a starter template`.
The template builder is the recommended way to create templates in Coder. It
guides you through selecting a base infrastructure template, adding modules
(IDEs, tools, integrations), and configuring your template, all without writing
Terraform.
![Create a template](../../images/admin/templates/create-template.png)
The template builder is enabled by default. When you select **New Template** on
the **Templates** page, the builder opens automatically.
From there, select a starter template for desired underlying infrastructure for
workspaces.
The builder guides you through up to five steps:
![Starter templates](../../images/admin/templates/starter-templates.png)
1. **Select base infrastructure**: Choose a starter template for your target
platform (e.g. Docker, AWS EC2, Kubernetes). Each base template provides a
working foundation with the Coder agent pre-configured.
Give your template a name, description, and icon and press `Create template`.
![Select a base infrastructure template in the template builder](../../images/templatebuilder_01_bases.png)
![Name and icon](../../images/admin/templates/import-template.png)
1. **Base template parameters** *(optional)*: If the selected base template
declares configurable variables, you can supply values for them here.
If the base template has no parameters, this step is skipped automatically.
If template creation fails, it's likely that Coder is not authorized to deploy infrastructure in the given location.
Learn how to configure [provisioner authentication](./extending-templates/provider-authentication.md).
1. **Select modules**: Pick from a curated list of
[registry modules](https://registry.coder.com) to add IDEs, AI agents,
source control integrations, and other tools. Modules are grouped by
category and filtered for compatibility with the selected base template's
operating system. You can select multiple modules.
![Select modules to add to your template](../../images/templatebuilder_02_modules.png)
1. **Module settings** *(optional)*: Configure variables for the modules you
selected. Required variables without defaults must be filled in before you
can proceed. Modules that require secrets (such as API keys) display a
notice that developers will be prompted for the value at workspace creation
time.
![Configure module settings](../../images/templatebuilder_03_module_customization.png)
1. **Template customizations**: Set the template's display name, description,
icon, and organization, then select **Create Template**.
![Set template display name, description, and other metadata](../../images/templatebuilder_04_customizations.png)
After you select **Create Template**, Coder composes the Terraform
configuration server-side, validates it with `terraform init` and
`terraform validate`, and creates the template. The generated template is
standard Terraform HCL that you can edit later through the dashboard or CLI.
> [!NOTE]
> The template builder requires outbound access to `registry.coder.com` so
> that `terraform init` can resolve module sources. For air-gapped or
> restricted-egress deployments, visit
> [Air-gapped deployments](../../install/airgap.md#template-builder).
If you select modules that are known to conflict with each other, the builder
displays a warning. Module conflicts do not block template creation, but you
should review the warning before proceeding.
#### Disabling the template builder
Operators can disable the template builder by setting the
`CODER_DISABLE_TEMPLATE_BUILDER` environment variable or the
`--disable-template-builder` server flag. When disabled, the **New Template**
button links to the starter templates page instead, and the
`/api/v2/templatebuilder/*` endpoints return 404.
Deployments using a self-hosted module registry mirror can set
`CODER_TEMPLATE_BUILDER_REGISTRY_URL` to point generated module source paths at
the mirror instead of `registry.coder.com`.
#### Alternative creation methods
The template builder's first step also links to alternative creation paths:
- **Upload an existing template**: Upload a `.tar.gz` or `.zip` of Terraform
files you have authored locally.
- **Start from scratch**: Follow the
[template from scratch tutorial](../../tutorials/template-from-scratch.md) to
write Terraform by hand.
- **Browse community templates**: Browse the
[Coder Registry](https://registry.coder.com/templates) for community and
official templates.
### CLI
You can the [Coder CLI](../../install/cli.md) to manage templates for Coder.
You can use the [Coder CLI](../../install/cli.md) to manage templates for Coder.
After [logging in](../../reference/cli/login.md) to your deployment, create a
folder to store your templates:
@@ -63,8 +128,9 @@ Next, push it to Coder with the
coder templates push
```
If `template push` fails, it's likely that Coder is not authorized to deploy infrastructure in the given location.
Learn how to configure [provisioner authentication](../provisioners/index.md).
If `templates push` fails, it is likely that Coder is not authorized to deploy
infrastructure in the given location. Learn how to configure
[provisioner authentication](../provisioners/index.md).
You can edit the metadata of the template such as the display name with the
[`templates edit`](../../reference/cli/templates_edit.md) command:
@@ -85,7 +151,7 @@ to manage templates via GitOps.
## From an existing template
You can duplicate an existing template in your Coder deployment. This will copy
You can duplicate an existing template in your Coder deployment. This copies
the template code and metadata, allowing you to make changes without affecting
the original template.
docs/admin/templates/index.md
+11 -8
View File
@@ -4,9 +4,10 @@ Templates are written in
[Terraform](https://developer.hashicorp.com/terraform/intro) and define the
underlying infrastructure that all Coder workspaces run on.
![Starter templates](../../images/admin/templates/starter-templates.png)
<small>The "Starter Templates" page within the Coder dashboard.</small>
The [template builder](./creating-templates.md#template-builder) is
the recommended way to create templates. It guides you through selecting base
infrastructure, adding modules, and configuring your template without writing
Terraform.
## Learn the concepts
@@ -18,12 +19,14 @@ If you are unfamiliar with Terraform, see
[Hashicorp's Tutorials](https://developer.hashicorp.com/terraform/tutorials) for
common cloud providers.
## Starter templates
## Create a template
After learning the basics, use starter templates to import a template with
sensible defaults for popular platforms (e.g. AWS, Kubernetes, Docker, etc).
Docs:
[Create a template from a starter template](./creating-templates.md#from-a-starter-template).
The fastest way to get started is with the
[template builder](./creating-templates.md#template-builder), which
composes a working template from a base infrastructure template and optional
registry modules. Starter templates for popular platforms (AWS, Kubernetes,
Docker, and others) are available as base templates in the builder, or through
the [CLI](./creating-templates.md#cli).
## Extending templates
docs/admin/templates/managing-templates/index.md
+12 -9
View File
@@ -14,18 +14,21 @@ any developer to propose changes to a template.
You can give different users and groups access to templates with
[role-based access control](../template-permissions.md).
## Starter templates
## Creating templates
We provide starter templates for common cloud providers, like AWS, and
orchestrators, like Kubernetes. From there, you can modify them to use your own
images, VPC, cloud credentials, and so on. Coder supports all Terraform
resources and properties, so fear not if your favorite cloud provider isn't
here!
The [template builder](../creating-templates.md#template-builder) is
the recommended way to create templates. It guides you through selecting a base
infrastructure template, adding modules (IDEs, tools, integrations), and
configuring template settings without writing Terraform.
![Starter templates](../../../images/start/starter-templates.png)
Starter templates for common cloud providers (AWS, Azure) and orchestrators
(Kubernetes, Docker) are available as base templates within the builder. You can
modify the generated template to use your own images, VPC, cloud credentials,
and so on. Coder supports all Terraform resources and properties.
If you prefer to use Coder on the
[command line](../../../reference/cli/index.md), `coder templates init`.
[command line](../../../reference/cli/index.md), use `coder templates init` to
pull a starter template, then `coder templates push` to upload it.
Coder starter templates are also available on our
[GitHub repo](../../../../examples/templates).
@@ -38,7 +41,7 @@ by our users
## Editing templates
Our starter templates are meant to be modified for your use cases. You can edit
Our templates are meant to be modified for your use cases. You can edit
any template's files directly in the Coder dashboard.
![Editing a template](../../../images/templates/choosing-edit-template.gif)