Files
coder/docs/admin/integrations/devcontainers/envbuilder/index.md
T
Nick Vigilante 16551fd67f feat: enable Coder.AbbreviationFirstUse (#30878)
Adds `Coder.AbbreviationFirstUse`, a Vale rule that requires each
abbreviation to be expanded on its first use on a page, in the form
"Expanded Form (ABBR)". It supports [WCAG 2.2 Level AAA Success
Criterion 3.1.4
(Abbreviations)](https://www.w3.org/TR/WCAG22/#abbreviations). Following
the "Adding a Vale rule" pattern in `docs/.style/README.md`, the PR has
two commits: the cleanup first, then the enable.

## Cleanup commit

431 first uses expanded across 167 pages, so the rule ships with zero
findings across `docs/`, excluding `docs/.style/style-guide/`. The
branch was rebuilt on current `main`, so pages added or moved since the
first draft are covered.

- Where the first use is a bold UI label (**CA Path**, **Add redirect
URI**, **Redirect URI**), the label stays as the UI shows it and the
expansion goes elsewhere in the same paragraph or list item.
- Reversed forms such as "PKCE (Proof Key for Code Exchange)" are
flipped to the expanded-first form.
- A few sentences took a small rewording to fit the expansion: list
steps that would pass the 20-word limit (`Coder.StepLength`), and spots
where the expansion would nest parentheses.
- MITM is expanded as "machine-in-the-middle" rather than
"man-in-the-middle". Every use describes the AI Gateway Proxy
intercepting traffic on purpose, so "on-path attacker" doesn't fit. The
inclusive-language table on `accessibility-and-inclusion.md` gains the
substitution: "on-path attacker" for the attack, "machine-in-the-middle"
for the feature.
- Unrelated fixes on lines already being edited: `DERP MAP` → `DERP
map`, and `ENV` → "environment variable" in `faqs.md`.

## Enable commit

**Rule design.** The rule is a `conditional`. `first` matches 2 to 6
capitals, each optionally followed by digits (`EC2`, `P2P`), and a
lookahead lets a plural `s` count as a use of the singular. `second`
captures the abbreviation in `word (ABBR)`, including `(CI/CD)` and
`(PCI DSS)` pairs. Vale collects the captures across the page's blocks
in document order, so a later expansion doesn't cover an earlier use.
Within a single paragraph, list item, or table cell, an expansion
anywhere in the block counts.

**Scope.** `scope: ~heading` skips headings, because a page title often
names an abbreviation that the first paragraph then expands. Vale
already skips front matter, code blocks, inline code, and link URLs.
`.vale.ini` turns the rule off for the pages generated from Go source
that `Coder.UnitSpacing` already skips: `docs/reference/{api,cli}/*.md`,
`configuration-reference.md`, and `prometheus.md`.

**Severity: `warning`.** Whether an abbreviation is familiar enough to
skip is a judgment call, so this is guidance with legitimate exceptions,
not hard policy.

**Exceptions**, each group commented in the rule file:

| Group | Entries | Reason |
| --- | --- | --- |
| Known to every reader | AI, API, AWS, CLI, CPU, DNS, GCP, HTTP(S), ID,
IDE, IP, JSON, OS, PR, RAM, SDK, SQL, SSH, TLS, UI, URL, VM, YAML |
Abbreviations every reader of the docs knows. Plurals such as VMs and
SDKs pass too |
| Units, clock times, file and package formats | GB, KB, MB, AM, PM,
CSV, GIF, JPEG, PDF, PNG, RPM, SVG, VSIX, ZIP | Readers know these by
the abbreviation, not the expansion |
| Not abbreviations | NOTE, TIP, OK, README, SKILL, ALL, AND, ANY,
ERROR, MUST, NOT, ON, OR, DELETE, GET, POST, PUT, ILIKE, VACUUM, LOGIN,
PLAIN, NUL, CRON, TERM, DOCS, `DOC\d+`, `RFC\d+`, TL, DR | Alert labels,
file names, emphasis in capitals, HTTP methods, SQL keywords, SMTP auth
mechanisms, rule labels in `docs/AGENTS.md`, RFC numbers, TL;DR |
| Names written in capitals | VS, IDEA, IU, NGINX, SUSE, GNU, XFCE, DX,
IBM, DCV, TRAMP, MSYS2, NET, VSX, ARM, AMD, GPT, AES, GCM, HMAC, HS256,
RSA, SHA, SHA256 | The capitals are the product, company, or algorithm
name (VS Code, IntelliJ IDEA, .NET, Open VSX, Amazon DCV, AMD) |

The "known to every reader" group is the list that needs judgment, and
it's the one to push back on. The other groups only stop the regex from
treating words and names as abbreviations.

**Documentation.** A new "Expand abbreviations on first use" section on
`accessibility-and-inclusion.md`, and the style guide README's checks
table, coverage table, and rule counts (90 → 91 rules, 22 → 23
tool-checked).

## Known limits

- The rule checks that an expansion exists, not that it's correct: any
word followed by `(ABBR)` satisfies it.
- An abbreviation in an image's alt text is checked before the paragraph
around it, so one alt text (`aws-marketplace.md`) carries its own
expansion.
- Some expansions read heavily in dense table cells and inline lists,
for example the four Kubernetes services in `docker-in-workspaces.md`.
They're correct, but a reviewer may prefer adding a specific
abbreviation to the exceptions instead.

## Testing

- `vale docs/` (Vale 3.7.1 through mise): zero
`Coder.AbbreviationFirstUse` findings. Findings from every other rule
match `main` file for file.
- `pnpm run format-docs`, `pnpm run lint-docs`,
`scripts/check_emdash.sh`, and `make lint/prose` run clean, and the
repository pre-commit hooks (including `lint/style-claims`) pass on both
commits.

Linear: DOCS-1311

Generated by Coder Agents on behalf of @nickvigilante.
2026-11-02 14:41:15 -05:00

2.7 KiB

title
title
Envbuilder

Warning

Envbuilder is in maintenance mode with no new features planned.

The recommended way to use dev containers in Coder is the built-in Dev Containers Integration. To find the best approach for your deployment, join our community to be guided towards the best approach.

Envbuilder is an open-source tool that builds development environments from dev container configuration files. Unlike the Dev Containers integration, Envbuilder transforms the workspace image itself rather than running containers inside the workspace.

Envbuilder is well-suited for Kubernetes-native deployments without privileged containers, environments where Docker is unavailable or restricted, and workflows where administrators need infrastructure-level control over image builds, caching, and security scanning. For workspaces with Docker available, the Dev Containers Integration offers container management with dashboard visibility and multi-container support.

Dev containers provide developers with increased autonomy and control over their Coder cloud development environments.

By using dev containers, developers can customize their workspaces with tools pre-approved by platform teams in registries like JFrog Artifactory. This simplifies workflows, reduces the need for tickets and approvals, and promotes greater independence for developers.

Prerequisites

An administrator should construct or choose a base image and create a template that includes a devcontainer_builder image before a developer team configures dev containers.

Devcontainer Features

Dev container Features allow owners of a project to specify self-contained units of code and runtime configuration that can be composed together on top of an existing base image. This is a good place to install project-specific tools, such as language-specific runtimes and compilers.

Coder Envbuilder

Envbuilder is an open-source project maintained by Coder that runs dev containers via Coder templates and your underlying infrastructure. Envbuilder can run on Docker or Kubernetes.

It is independently packaged and versioned from the centralized Coder open-source project. This means that Envbuilder can be used with Coder, but it is not required. It also means that dev container builds can scale independently of the Coder control plane and even run within a continuous integration and continuous delivery (CI/CD) pipeline.

Next steps