Files
coder/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md
T
Nick Vigilante bc77c40296 docs: add front-matter titles to mechanical and no-H1 pages (Phase 3) (#28030)
## Summary

**Batch A of Phase 3** of the H1 → front-matter migration (`DOCS-484`;
parent `DOCS-477`). Adds a front-matter `title` to every navigable docs
page whose title can be migrated **mechanically**, with no editorial
judgment.

This is the content step that Phase 1 (renderers prefer front-matter
title, `DOCS-482`) and Phase 2 (tooling + generators front-matter-aware,
`DOCS-483`) unblocked. Both are merged; coder.com #964/#974 are merged
and live.

**Rendered no-op.** The renderers already resolve the page title from
the manifest and hide the leading body H1 (Phase 1), so no page changes
visually. This just moves the title into front matter where Fumadocs and
the migrated tooling can read it.

## What's in this batch

Dry-run on `main` (464 navigable pages) splits into:

| category | count | this PR |
|----------|-------|---------|
| already has front-matter title (Reference, from Phase 2 generators) |
196 | skipped (idempotent) |
| **mechanical** — leading body H1 equals the manifest label | 138 | ✅
add front-matter `title`, drop the duplicate H1 |
| **no body H1** — renders under the manifest label only | 4 | ✅ add
front-matter `title` only |
| **mismatch** — body H1 differs from the manifest label | 126 | ⏭️
deferred (needs an editorial decision, see below) |

142 files changed, all under `docs/`.

## Deliberately out of scope: the 126 mismatches

Pages where the body H1 is richer than the short sidebar label (e.g.
label **Modules** / H1 *Contributing modules*, label **Install** / H1
*Installing Coder*) need a canonical-title decision, not a script. A few
even look like the body H1 is the redundant one (`install/cli.md` and
`install/index.md` both carry the H1 *Installing Coder*). These will
land in follow-up batches **by nav section** once the policy is set, so
each gets real review.

## Verification

AI was the primary author of this PR (see disclosure below); per the [AI
Contribution
Guidelines](https://coder.com/docs/about/contributing/AI_CONTRIBUTING)
here is the manual verification.

- Every added front-matter block parses as YAML and its `title`
round-trips to the manifest label (checked programmatically across all
142 files).
- Every removed line is a leading `# H1` that equalled the manifest
title; no body prose was reflowed. Front matter is correctly hoisted
above pre-existing `<!-- markdownlint-disable -->` comments on the two
pages that had them.
- `pnpm check-docs` (markdownlint-cli2 + table formatter) passes on the
changed set: `Summary: 0 error(s)`. `MD041` stays off (re-enabled in
Phase 4); `MD025` is not tripped because the duplicate body H1s are
removed.

```
$ pnpm exec markdownlint-cli2 $(git diff --name-only origin/main)
Linting: 142 file(s)
Summary: 0 error(s)
```

Linear: DOCS-484

> This PR was created with AI assistance (Coder Agents).
2026-08-27 12:34:13 -04:00

137 lines
5.6 KiB
Markdown

---
title: Add an Envbuilder template
---
A Coder administrator adds an Envbuilder-compatible template to Coder. This
allows the template to prompt the developer for their dev container repository's
URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create
their workspace. Envbuilder clones the repo and builds a container from the
`devcontainer.json` specified in the repo.
You can create template files through the Coder dashboard, CLI, or you can
choose a template from the
[Coder registry](https://registry.coder.com/templates):
<div class="tabs">
## Dashboard
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
1. Use the `template init` command to initialize your choice of image:
```sh
coder template init --id kubernetes-devcontainer
```
A list of available templates is shown in the
[templates_init](../../../../reference/cli/templates.md) reference.
1. `cd` into the directory and push the template to your Coder deployment:
```sh
cd kubernetes-devcontainer && coder templates push
```
You can also edit the files or make changes to the files before you push them
to Coder.
## Registry
1. Go to the [Coder registry](https://registry.coder.com/templates) and select a
dev container-compatible template.
1. Copy the files to your local device, then edit them to fit your needs.
1. Upload them to Coder through the CLI or dashboard:
- CLI:
```sh
coder templates push <template-name> -d <path to folder containing main.tf>
```
- Dashboard:
1. Create a `.zip` of the template files:
- On Mac or Windows, highlight the files and then right click. A
"compress" option is available through the right-click context menu.
- To zip the files through the command line:
```sh
zip templates.zip Dockerfile main.tf
```
1. Select **Templates**.
1. Select **Create Template**, then **Upload template**:
![Upload template](../../../../images/templates/upload-create-your-first-template.png)
1. Drag the `.zip` file into the **Upload template** section and fill out the
details, then select **Create template**.
![Upload the template files](../../../../images/templates/upload-create-template-form.png)
</div>
To set variables such as the namespace, go to the template in your Coder
dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
<img height="255px" src="../../../../images/templates/template-menu-settings.png" alt="Choose Settings from the template's menu" align="center" />
## Envbuilder Terraform provider
When using the
[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs),
a previously built and cached image can be reused directly, allowing dev
containers to start instantaneously.
Developers can edit the `devcontainer.json` in their workspace to customize
their development environments:
```json
# …
{
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {}
}
}
# …
```
## Example templates
| Template | Description |
|-------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| [Docker dev containers](../../../../../examples/templates/docker-devcontainer) | Docker provisions a development container. |
| [Kubernetes dev containers](../../../../../examples/templates/kubernetes-devcontainer) | Provisions a development container on the Kubernetes cluster. |
| [Google Compute Engine dev container](../../../../../examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
| [AWS EC2 dev container](../../../../../examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
Your template can prompt the user for a repo URL with
[parameters](../../../templates/extending-templates/parameters.md):
![Dev container parameter screen](../../../../images/templates/devcontainers.png)
## Dev container lifecycle scripts
The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
`postStartCommand` lifecycle scripts are run each time the container is started.
This could be used, for example, to fetch or update project dependencies before
a user begins using the workspace.
Lifecycle scripts are managed by project developers.
## Next steps
- [Envbuilder security and caching](./envbuilder-security-caching.md)