mirror of
https://github.com/coder/coder.git
synced 2026-09-22 05:05:20 +08:00
Nick Vigilante
f5e0c1a860
## What
Fixes three classes of invalid inline HTML in hand-written docs, all of
which
render incorrectly (or only render by accident) today. Found via a
systematic,
markdown-aware audit of every `.md` under `docs/` (ignores code blocks,
inline
code, comments, and autolinks), so this is a complete sweep of the
hand-written
surface, not a spot fix.
## Changes
1. **`<kdb>` → `<kbd>` (72 tags).** The keyboard element is `<kbd>`;
`<kdb>` is
a typo that is not a real element, so renderers drop/mangle it and the
keystrokes lose their styling. Corrected across the IDE access guides
(`cursor.md`, `windsurf.md`, `antigravity.md`). The correct `<kbd>` is
already used in the JetBrains Gateway guide.
2. **Unclosed `<div class="tabs">` in `docs/admin/users/idp-sync.md`.**
The
"Provider-Specific Guides" section opened a `.tabs` container (rendered
as
the `DocsTabs` component) that was never closed, so the wrapper leaked
over
the rest of the page. Added the missing `</div>` before `## Next Steps`,
matching the three other tab sections in the same file.
3. **`<Image>` → `<img>` (6 tags).** `<Image>` is not a registered docs
component — it renders only because the HTML5 parser rewrites the legacy
`<image>` tag to `<img>`. Converted to lowercase `<img>` for correctness
and
clarity; rendering is unchanged. (`organizations.md`, `idp-sync.md`,
`add-envbuilder.md`.)
## Scope / what is intentionally not here
- **Generated reference docs.** The audit also found swallowed
placeholders in
generated pages (`<server>` in `reference/api/{chats,schemas}.md`;
`<glob>`/`<host>` in `agent-firewall`; `<region>` in `server`). Those
are
fixed at the generator source (codersdk comments / CLI flag help) and
tracked
in DOCS-551.
- **`<b>Resource<b>`** in the generated audit-logs table was fixed
separately in
#27293 (merged) and is not duplicated here.
- **`<children></children>`** is an intentional, renderer-implemented
docs
component (child-page card grid) with no HTML equivalent, so it is left
as-is.
It is well-formed; a follow-up CI checker will still verify its
open/close
balance.
A follow-up adds CI enforcement so invalid inline HTML can't regress.
<details>
<summary>Verification</summary>
Run against the changed files:
- `markdownlint-cli2` — 0 errors
- `markdown-table-formatter --check` — no changes needed
- `typos --config .github/workflows/typos.toml` — clean
- Re-running the audit scanner: hand-written `unclosed`, `<kdb>`, and
capitalized-component findings all drop to 0 (only the generated-doc
placeholders tracked in DOCS-551 remain).
</details>
## Linear
DOCS-581:
https://linear.app/codercom/issue/DOCS-581/audit-and-fix-all-invalid-html-across-the-docs
> This PR was created with AI assistance (Coder Agents).
135 lines
5.6 KiB
Markdown
135 lines
5.6 KiB
Markdown
# 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**:
|
|
|
|
|
|
|
|
1. Drag the `.zip` file into the **Upload template** section and fill out the
|
|
details, then select **Create template**.
|
|
|
|
|
|
|
|
</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 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)
|