## Summary Threads the deployment's configured module registry (`CODER_TEMPLATE_BUILDER_REGISTRY_URL`) into template-builder **base** rendering, so a base that embeds a catalog module (e.g. the quickstart base's `git-clone`) resolves its `source` through a registry mirror the same way wizard-composed modules already do. Previously base-embedded module sources hardcoded `registry.coder.com`, so on a mirror/private-registry deployment a base-embedded module reached the public registry while wizard modules used the mirror. Implements [DOCS-610](https://linear.app/codercom/issue/DOCS-610). ## What changed * `BaseRenderContext.RegistryBase` (new field), mirroring `ModuleRenderContext.RegistryBase`. `Compose` threads the deployment registry through `renderBase` into the base render context, and the four hardcoded base module sources (`quickstart` git-clone, `azure-linux`/`gcp-linux`/`gcp-windows` region modules) now use `{{ .RegistryBase }}`. Because the value defaults back to `registry.coder.com`, rendered sources stay byte-identical; the only golden change is the removal of the now-stale quickstart "follow-up" note. * **Boot-time validation.** `codersdk.ValidateTemplateBuilderRegistryURL` runs in `DeploymentValues.Validate()`, gated on the builder being enabled, matching the chat-hook precedent. A malformed value fails at server start naming the option, instead of surfacing as a per-request error to a template author who cannot fix it. It uses `net/url` in authority form to reject a scheme, path, query, fragment, trailing slash, or credentials and accept a bare `host[:port]`; it does not canonicalize the host. * `Compose` **trusts the validated value**, defaulting an unset one and defensively rejecting a malformed one for direct callers that bypass boot. ## Tests * `codersdk`: validator accept/reject matrix (incl. credentials-without-echo) and a `DeploymentValues.Validate` boundary test with a disabled-skips-validation case. * `templatebuilder`: a base honors the mirror and falls back to the default when unset, plus a defensive-reject case; existing compose tests updated to bare-host registry values. <details><summary>Design decision log</summary> This PR is a deliberately minimal reimplementation of the [DOCS-610](https://linear.app/codercom/issue/DOCS-610/template-builder-base-embedded-modules-should-honor-the-deployment) scope, started fresh from `main` rather than carrying forward an earlier, larger draft (coder/coder#28480). Key decisions: * **Scope kept to the ticket.** The ticket's fix is three bullets: add a registry field to `BaseRenderContext`, thread the deployment `RegistryURL` through `Compose` -> `renderBase`, and use it in base module sources. Independent hardening explored in the earlier draft was dropped as out of scope: `terraform-svchost`-based IDN/punycode/port canonicalization, a rendered-HCL backstop with a 500 mapping, and HCL module-source extraction helpers. Telemetry misclassification of mirror modules is tracked separately ([DOCS-712](https://linear.app/codercom/issue/DOCS-712/telemetry-misclassifies-registry-mirror-modules-as-non-coder)) and is not addressed here. * **Default lives in the render layer.** `templatebuilder.DefaultRegistryBase` holds the fallback host; `codersdk` keeps its own option-default literal. An earlier version exported the constant from `codersdk`, which only emitted a dead `typesGenerated.ts` entry that nothing in the frontend consumed, so it was moved out. The `codersdk` validator is a function, so it generates no TS type. * **Validate at the config boundary, fail fast.** The repo convention is to hard-fail structurally invalid config in `DeploymentValues.Validate()` (access URL, OAuth lifetimes, chat hook URL) and to warn only for functional-but-risky settings. A malformed registry host is structurally invalid, so it fails at boot. This also puts the error in front of the admin who set it, rather than a template author hitting a per-request error they cannot fix. * `net/url`**, not a regex.** The codebase validates identifiers/names with regexes but host/URL-shaped config with `url.Parse` (chat hook URL, OAuth redirect URIs, AI provider base URL). This value is host-shaped, so it follows that convention. `url.Parse("//" + v)` with `u.Host == v` rejects a scheme/path/query/fragment/trailing-slash in one check. </details> > This PR was created with AI assistance (Coder Agents).
8.0 KiB
title
| title |
|---|
| Creating Templates |
Users with the Template Administrator role or above can create templates
within Coder.
From a starter template
In most cases, it is best to start with a starter template.
Template builder
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.
The template builder is enabled by default. When you select New Template on the Templates page, the builder opens automatically.
The builder guides you through up to five steps:
-
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.
-
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.
-
Select modules: Pick from a curated list of registry modules 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.
-
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.
-
Template customizations: Set the template's display name, description, icon, and organization, then select Create Template.
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.comso thatterraform initcan resolve module sources. For air-gapped or restricted-egress deployments, visit Air-gapped deployments.
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.
The value is a bare host, optionally with a port (for example mirror.internal:8443).
A leading http(s):// scheme and trailing slash are stripped, and a path, query, fragment, or credentials is rejected at server start.
Alternative creation methods
The template builder's first step also links to alternative creation paths:
- Upload an existing template: Upload a
.tar.gzor.zipof Terraform files you have authored locally. - Start from scratch: Follow the template from scratch tutorial to write Terraform by hand.
- Browse community templates: Browse the Coder Registry for community and official templates.
CLI
You can use the Coder CLI to manage templates for Coder.
After logging in to your deployment, create a folder to store your templates:
# This snippet applies to macOS and Linux only
mkdir $HOME/coder-templates
cd $HOME/coder-templates
Use the templates init command to
pull a starter template:
coder templates init
After pulling the template to your local machine (e.g. aws-linux), you can
rename it:
# This snippet applies to macOS and Linux only
mv aws-linux universal-template
cd universal-template
Next, push it to Coder with the
templates push command:
coder templates push
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.
You can edit the metadata of the template such as the display name with the
templates edit command:
coder templates edit universal-template \
--display-name "Universal Template" \
--description "Virtual machine configured with Java, Python, Typescript, IntelliJ IDEA, and Ruby. Use this for starter projects. " \
--icon "/emojis/2b50.png"
CI/CD
Follow the change management guide to manage templates via GitOps.
From an existing template
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.
Web UI
After navigating to the page for a template, use the dropdown menu on the right
to Duplicate.
Give the new template a name, icon, and description.
Press Create template. After the build, you will be taken to the new template
page.
CLI
First, ensure you are logged in to the control plane as a user with permissions to read and write permissions.
coder login
You can list the available templates with the following CLI invocation.
coder templates list
After identified the template you'd like to work from, clone it into a directory with a name you'd like to assign to the new modified template.
coder templates pull <template-name> ./<new-template-name>
Then, you can make modifications to the existing template in this directory and
push them to the control plane using the -d flag to specify the directory.
coder templates push <new-template-name> -d ./<new-template-name>
You will then see your new template in the dashboard.
From scratch (advanced)
There may be cases where you want to create a template from scratch. You can use any Terraform provider with Coder to create templates for additional clouds (e.g. Hetzner, Alibaba) or orchestrators (VMware, Proxmox) that we do not provide example templates for.
Refer to the following resources:
- Tutorial: Create a template from scratch
- Extending templates: Features and concepts around templates (agents, parameters, variables, etc)
- Coder Registry: Official and community templates for Coder
- Coder Terraform Provider Reference






