## Summary
Adds the **Coder Quickstart** template as a selectable base in the
[template builder](coderd/templatebuilder) guided wizard. It is a
Docker-based starter that lets a user pick languages and optionally
clone a repo.
## What changed
- **New base package** `coderd/templatebuilder/bases/quickstart/`:
- `base.json`: `id: "quickstart"`, `display_name: "Coder Quickstart"`,
`os: "linux"`.
- `main.tf.tmpl`: a Docker workspace with a language selector, a single
language-install script, an optional Git clone, and workspace presets.
Editors are added via the builder's module step rather than baked into
the base.
- `install-languages.sh.tftpl` and `README.md` (with prerequisites
markers so the builder can extract the prerequisites section).
- **Placement**: the bases endpoint returns a plain list sorted by
display name (with ID as a deterministic tiebreak). The wizard's
base-infra select step prioritizes the Quickstart and Docker starters to
the front on the client, mirroring the existing client-side module
prioritization in `ModuleSelectStep` (shared `sortByPriority` helper).
- **Base/module collision guard**: a base's bundled catalog modules are
derived from its rendered Terraform (`ExtractModuleNames`, cached with
`sync.OnceValues` and filtered to catalog IDs). `validateModules` seeds
its seen-set from that derived set, so a wizard-selected module the base
already renders is rejected with a clear error, and the modules endpoint
omits it so the wizard never offers a colliding module. The base's
Terraform is the single source of truth, so there is no separate
manifest list that can drift.
## Testing
- `go test ./coderd/` (template builder handler: bases ordering, the
`baseSpec` table, the modules-endpoint base filter): pass.
- `go test ./coderd/templatebuilder/` (all-bases render/snapshot, the
collision guard, `TestBaseIncludedModules`, the selector/install-script
drift test): pass.
- `gofmt`, `go vet`, `golangci-lint`: clean.
- Frontend `tsc`, `biome`, and `knip`: clean.
## Review decisions
- **Template scope**: trimmed to infrastructure, a language selector,
and an optional Git clone. The IDE selector was removed; editors are
added via the builder's module step.
- **Placement**: base ordering is presentational, so it lives on the
client base-infra select step rather than in the API.
- **git-clone in the base**: kept for the build-time clone affordance.
The base renders its module source verbatim, so it currently pins the
public registry and does not yet honor a deployment's registry mirror;
that fix is tracked in DOCS-610 and delivered as a stacked follow-up PR
(an in-code note documents the current behavior).
- **Container image**: left hardcoded
(`codercom/enterprise-base:ubuntu`). The quickstart base is the
opinionated path; the Docker base covers custom images. Revisiting a
`container_image` variable is tracked in DOCS-611.
## Review updates (@jeremyruppel)
- **Ordering moved to the client**: deleted the server-side
Quickstart-before-Docker grouping (and its position test); the
base-infra select step now prioritizes bases client-side via a shared
`sortByPriority` helper, following the `ModuleSelectStep` precedent. The
API just returns a stable, name-sorted list.
- **Derive included modules from render**: dropped the
`included_modules` manifest field and the `IncludedModules` struct
field; `BaseIncludedModules` now derives from the rendered base (single
source of truth). Removed `TestBaseIncludedModulesMatchRendered` and
added a direct `TestBaseIncludedModules`.
- **Kept the PR scoped to "add quickstart base"**: reverted
`ExtractAgentResourceName`/`ExtractModuleNames` to the pre-`hclsyntax`
regex extraction and removed the option/preset HCL extractor family; the
selector↔install-script drift test now uses a small regex. The broader
templatebuilder HCL migration and the preset-language subset guard are
tracked in DOCS-735.
- Branch rebased onto `origin/main` (no content changes beyond the
above).
---
Linear:
[DOCS-558](https://linear.app/codercom/issue/DOCS-558/add-coder-quickstart-template-to-template-builder)
> This PR was created with AI assistance (Coder Agents).
Makes it easier to pick the right workspace image, both in the template
builder and in the docs.
- Template builder: the Docker and Kubernetes bases now expose a
`container_image` variable in the wizard (freeform text, defaults to
`codercom/example-base:ubuntu`), and their prerequisites explain why
image choice matters, with tradeoffs between
`codercom/example-base:ubuntu` (minimal) and
`codercom/example-universal:ubuntu` (catch-all), plus pointers to
[coder/images](https://github.com/coder/images) and the image management
docs.
- Docs: reworked [image
management](https://coder.com/docs/@ben%2Fdevrel-201-image-guidance-prereqs/admin/templates/managing-templates/image-management)
into a clearer maturity ladder (minimal → golden → project-specific →
developer customization), with pullable image references in every
example, `codercom/oss-dogfood` as a project-specific example, and Dev
Containers + [mise](https://mise.jdx.dev/) as ways to customize without
new images.
Companion PR for the starter templates: coder/registry#943
Part of DEVREL-201.
🤖 Generated with Coder Agents using Claude, on behalf of @bpmct (wizard
variable by @jeremyruppel in #27024)
---------
Co-authored-by: Jeremy Ruppel <jeremyruppel@users.noreply.github.com>
Add 6 new base templates to the template builder, covering all major
cloud providers and platforms:
- **scratch**: Minimal starter template with only `coder_agent` and
metadata
- **aws-windows**: AWS EC2 Windows instances with PowerShell user_data
- **azure-linux**: Azure VMs with cloud-init and managed disk
persistence
- **gcp-linux**: Google Compute Engine Linux instances with persistent
disk
- **gcp-windows**: Google Compute Engine Windows instances
- **digitalocean-linux**: DigitalOcean Linux droplets with persistent
volumes
Each base includes `base.json`, `main.tf.tmpl`, `README.md` (with
prerequisite markers), and any static files (cloud-init configs). Tests
verify all 9 bases load, render without error, and produce valid
single-agent declarations.
`azure-windows` is deferred; it needs to be registered in the `examples`
package first.
Depends on #26633
> [!NOTE]
> This PR was authored by Coder Agents on behalf of @jeremyruppel.
---
NB: This is very much an agent-generated PR and draws completely from
base templates that exist in `examples/templates/`. The base.json files
are new, so review those, but don't spend any brain tokens on the
correctness of the terraform and supporting files: any issues there are
issues with the upstream example template
Surface base template prerequisites to admins before they create a
template in the Template Builder wizard.
Today, template prerequisites (Docker socket setup, Kubernetes auth, AWS
IAM policies) are only visible in the registry README after import.
Admins hit opaque provisioner errors and have to hunt for docs. This
change extracts the prerequisites from the README and serves them via
the API so the frontend can display them inline.
## How it works
Each base template README uses HTML comment markers (`<!--
prerequisites:start -->` / `<!-- prerequisites:end -->`) to delimit the
prerequisites section. At boot time, the base catalog loader reads the
README, extracts the content between markers via `strings.Index`, and
caches both the full README and the prerequisites string.
The prerequisites are served via a new `prerequisites` field on `GET
/api/v2/templatebuilder/bases`. The full README is included in the
composed template tar bundle and stored as the template version readme.
## Changes
- Add `README.md` with prerequisite markers to
`coderd/templatebuilder/bases/{docker,kubernetes,aws-linux}/`
- New `ExtractPrerequisites()` in `prerequisites.go` using literal
string matching
- `bases.go`: load README at boot, fail loudly if missing, extract
prerequisites
- `compose.go`: include README in `ComposeResult` and tar bundle
- `codersdk`: add `Prerequisites` field to `TemplateBuilderBase`
- Handler: populate prerequisites in bases response, set readme on
template version
<details>
<summary>Implementation notes</summary>
- Prerequisites extraction uses `strings.Index` for exact literal marker
matching; no regex or AST parser needed since we control the markers.
- YAML frontmatter is deliberately retained in the stored README. The
frontend `TemplateDocsPage` already strips it at render time via
`front-matter`.
- The prerequisite markers are HTML comments, invisible in rendered
markdown.
- The `RejectsMissingReadme` test enforces that every base template must
include a README.
- AWS Linux prerequisites span two H2 sections (`## Prerequisites` and
`## Required permissions / policy`), which is why heading-based parsing
was rejected in favor of explicit markers.
*Generated with the assistance of an AI coding agent. Reviewed by
@jeremyruppel.*
</details>
Relates to https://linear.app/codercom/issue/DEVEX-446
Add the bundled `exampleID -> OS` Go map for Docker, Kubernetes, and AWS
EC2 Linux base templates. Create `.tf.tmpl` Go template files for each
within `coderd/templatebuilder/bases/`, along with `BaseRenderContext`
and `RenderBaseTemplate` rendering helpers.
The `.tf.tmpl` files are independent copies of the example templates
with module blocks (code-server, jetbrains) removed, since the template
builder composes modules separately into `modules.tf`. When
`ImageOptions` is provided, the container image field references the
Terraform parameter; otherwise it uses the hardcoded value via Go
template whitespace control (`{{-`).
Golden file snapshot tests verify rendered output stability with an
`-update` flag for regeneration.
Depends on #25909
> [!NOTE]
> This PR was authored by Coder Agents on behalf of @jeremyruppel.