Codestin Search App

jeremyruppel · 2026-07-06T13:55:38Z

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)

Implementation plan

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

docs/admin/templates/creating-templates.md (primary creation docs, most content)
docs/get-started/index.md (quickstart)
docs/start/first-template.md (beginner tutorial)
docs/admin/templates/index.md (overview)
docs/admin/templates/managing-templates/index.md (managing overview)
docs/install/airgap.md (airgap note)
docs/tutorials/template-from-scratch.md (from-scratch tutorial)
docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md (envbuilder)
docs/about/screenshots.md (screenshot captions)
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).

🤖 Generated by Coder Agents

Update documentation across 9 files to reflect the template builder as the primary template creation method. The builder is a guided wizard that lets admins select base infrastructure, add registry modules, and produce validated Terraform without writing HCL. - Add template builder section to creating-templates.md as primary path - Update quickstart and first-template tutorials to use the builder - Add template builder screenshots for each wizard step - Add air-gapped deployment notes for CODER_DISABLE_TEMPLATE_BUILDER and CODER_TEMPLATE_BUILDER_REGISTRY_URL - Update secondary references in managing-templates, envbuilder, template-from-scratch, and screenshots docs - Fix existing typos and inconsistencies in template docs

github-actions · 2026-07-06T13:55:48Z

Docs preview

📖 View docs preview for docs/about/screenshots.md

No devcontainer-compatible base templates exist in the builder yet, so the envbuilder docs should keep the existing flow.

Keep the <div class="tabs"> structure with Template builder, CLI, and CI/CD as parallel creation methods under "From a starter template". Update cross-reference anchors in index.md, managing-templates, and template-from-scratch to match the new heading.

coderagents · 2026-07-06T14:18:25Z

Documentation Check

Updates Needed

docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md - Dashboard tab updated to reference the template builder and "Upload an existing template" alternative.
docs/admin/templates/managing-templates/index.md - ~~Lines 33-34, 38, and 44 still use "starter templates" phrasing.~~ Line 44 was updated ("Our templates"). Remaining uses on lines 31 and 33 describe the CLI coder templates init workflow where "starter template" is accurate terminology.
docs/start/first-workspace.md - "The Docker starter template" updated to "The Docker template".

Cleanup Suggested

7 orphaned images are now deleted in this PR.

Automated review via Coder Agents

- Update 'starter template' phrasing in first-workspace.md and managing-templates/index.md - Remove 7 orphaned images no longer referenced by any doc

Direct users to the upload flow via the builder's alternative links since no devcontainer-compatible base templates exist in the builder yet.

nickvigilante

Overall really solid PR! I do want to chat with you separately about the base template used in the Get Started guide, just because I've planned a few deliberate tutorials based on the existing Coder Quickstart template, so I want to strategize with you on that a bit. I'll reach out separately.

nickvigilante · 2026-07-06T14:44:51Z

This file isn't part of manifest.json, so I wonder if it's even necessary to edit this. No action as of now; this won't affect the review. Probably a note for me to move us to use YAML front matter and include draft: true to avoid editing files more than necessary.

nickvigilante · 2026-07-06T14:47:56Z

Same thing about this not being in the manifest.json. No action here.

- Use 'guides you through' instead of 'walks you through' (inclusive) - Replace 'this step lets you' with direct phrasing (Red Hat style) - Use 'visit' instead of 'see' for screen reader accessibility - Use '>' for UI element chaining (Microsoft convention) - Convert Docker note to [!NOTE] block, remove exclamation point - Fix VS Code Desktop mention (enabled by default), use Claude Code and JetBrains as examples instead - Apply one-sentence-per-line in envbuilder Dashboard tab - Use 'dev-container-compatible' hyphenation in envbuilder doc

nickvigilante

LGTM! Thanks for writing this up 🚀

github-actions Bot assigned jeremyruppel Jul 6, 2026

jeremyruppel added 5 commits July 6, 2026 14:00

docs: revert envbuilder template creation changes

b337ce3

No devcontainer-compatible base templates exist in the builder yet, so the envbuilder docs should keep the existing flow.

docs: restore original CLI tab intro text

e4817f5

docs: remove secrets line, fix defaults reference

5657b49

docs: add template builder screenshots to first-template tutorial

a4dcd79

jeremyruppel requested a review from nickvigilante July 6, 2026 14:15

docs: fix broken anchor link to CLI section

5670304

jeremyruppel marked this pull request as ready for review July 6, 2026 14:15

jeremyruppel added 2 commits July 6, 2026 14:22

docs: address doc-check feedback

a1a757b

- Update 'starter template' phrasing in first-workspace.md and managing-templates/index.md - Remove 7 orphaned images no longer referenced by any doc

docs: update envbuilder Dashboard tab for template builder

6ad9f1b

Direct users to the upload flow via the builder's alternative links since no devcontainer-compatible base templates exist in the builder yet.

jeremyruppel commented Jul 6, 2026

View reviewed changes

Comment thread docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md Outdated

nickvigilante reviewed Jul 6, 2026

View reviewed changes

nickvigilante approved these changes Jul 6, 2026

View reviewed changes

jeremyruppel merged commit 79fc854 into main Jul 6, 2026
30 of 31 checks passed

jeremyruppel deleted the docs/template-builder branch July 6, 2026 15:16

github-actions Bot locked and limited conversation to collaborators Jul 6, 2026

jeremyruppel added the cherry-pick label Jul 7, 2026

Navigation Menu

Uh oh!

docs: update template creation docs for template builder - #26993

docs: update template creation docs for template builder#26993
jeremyruppel merged 10 commits into
mainfrom
docs/template-builder

jeremyruppel commented Jul 6, 2026

Uh oh!

github-actions Bot commented Jul 6, 2026

Uh oh!

coderagents Bot commented Jul 6, 2026 •

edited

Loading

Uh oh!

Uh oh!

nickvigilante left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nickvigilante Jul 6, 2026

Uh oh!

nickvigilante Jul 6, 2026

Uh oh!

nickvigilante left a comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

jeremyruppel commented Jul 6, 2026

Summary

Changes

Plan: Update docs/ for Template Builder Launch

Summary

Key behavioral facts from the code

Files to update

Tier 1: Primary creation flow docs (significant rewrites)

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

2. docs/start/first-template.md

3. docs/get-started/index.md

Tier 2: Secondary references (targeted edits)

4. docs/admin/templates/index.md

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

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

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

8. docs/install/airgap.md

9. docs/about/screenshots.md

Tier 3: Minor/link-only updates

10. docs/admin/users/organizations.md

11. docs/ai-coder/tasks.md

Files NOT to update

Implementation order

Style notes

Uh oh!

github-actions Bot commented Jul 6, 2026

Docs preview

Uh oh!

coderagents Bot commented Jul 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation Check

Updates Needed

Cleanup Suggested

Uh oh!

Uh oh!

nickvigilante left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

nickvigilante Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

nickvigilante Jul 6, 2026

Choose a reason for hiding this comment

Uh oh!

nickvigilante left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

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

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

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

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

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

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

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

8. `docs/install/airgap.md`

9. `docs/about/screenshots.md`

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

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

coderagents Bot commented Jul 6, 2026 •

edited

Loading