## Summary **Batch B of Phase 3** of the H1 → front-matter migration (`DOCS-484`; parent `DOCS-477`), the editorial follow-up to Batch A (#28030). For the **124** hand-authored pages whose leading body H1 differed from the manifest nav label, this promotes the richer body H1 to the front-matter **page title** and drops the duplicate H1, while keeping the short manifest **label** as the sidebar entry. Policy agreed with the docs owner: - Short sidebar labels win. Duplicate sidebar labels are acceptable. - Identical **page titles** across two pages are not. On a collision, rename the non-generated page's title. ## Page-title collisions resolved Promoting the H1 created 4 page-title collisions; each is disambiguated by renaming the non-generated / secondary page (sidebar labels left unchanged): | page | sidebar label | body H1 | → page title | |------|---------------|---------|--------------| | `install/index.md` | Install | Installing Coder | **Install Coder in your infrastructure** | | `install/cli.md` | Coder CLI | Installing Coder | **Install the Coder CLI** | | `ai-gateway/clients/jetbrains.md` | JetBrains | JetBrains IDEs | **JetBrains** | | `workspace-access/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | Web IDEs *(kept — primary user guide)* | | `extending-templates/web-ides.md` | Web IDEs and Coder Apps | Web IDEs | **Web IDEs in templates** | | `workspace-management.md` | Workspace Management | Workspaces | **Manage workspaces** *(vs generated `api/workspaces.md`)* | These titles are the only non-mechanical editorial calls in this PR. ## Deliberately excluded: generated pages `admin/security/audit-logs.md` and `admin/setup/configuration-reference.md` are `make gen` outputs (`auditdocgen` / `configdocgen`) that Phase 2 did **not** update, so a hand-added title would be reverted on the next generation. They're excluded here and need their generators taught to emit front matter first (Phase 2 pattern), tracked as `DOCS-631`. Batch A (#28030) had the same issue for three other generated pages; it has been corrected there too. ## 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. - Promote = set front-matter `title` to the body H1 (or the disambiguated title above) and remove that one duplicate H1. No other body prose is reflowed. - Every added front-matter block parses as YAML; all files pass `pnpm check-docs` (markdownlint-cli2 + table formatter): `Summary: 0 error(s)`. - Removing the H1 orphaned one in-page fragment (`[MCP](#mcp)` in `ai-gateway/mcp.md`), now repointed. A cross-file fragment audit into the retitled pages found no real breakage. Anchor-change note Unlike Batch A (title unchanged, a rendered no-op), Batch B changes each page's effective title from the manifest label to the body H1, so the rendered H1 **anchor slug changes**. An audit of cross-file `.md#fragment` links into these pages surfaced no links that break as a result (the only hits were false positives against a still-present `## TLS & Reverse Proxy` heading). Same-file fragments are enforced by markdownlint MD051, which is green. ## Title casing (follow-up, DOCS-742) A follow-up commit puts the promoted titles into sentence case and removes leading gerunds (for example, `Managing workspace schedules` → `Manage workspace schedules`): 57 of the 120 titles changed, the other 63 were already compliant. Proper nouns and branded names (Coder Validated Architecture, JetBrains, File Browser, Dev Containers, Island), acronyms (API, CLI, IDE, MCP, OIDC, URL, UI, CI/CD), the Premium license tier, and maturity labels (Beta, Experimental) are preserved. The four `Nk-users` pages become `Reference architecture: up to N users` (lowercase, matching the CVA landing page's own usage); the CVA landing page keeps its branded title. `pnpm check-docs`: `Summary: 0 error(s)`. Linear: DOCS-484, DOCS-742 > This PR was created with AI assistance (Coder Agents).
321 lines
11 KiB
Markdown
321 lines
11 KiB
Markdown
---
|
|
title: Configure a template for Dev Containers
|
|
---
|
|
|
|
This guide covers the Dev Containers Integration, which uses Docker. For
|
|
environments without Docker, see [Envbuilder](./envbuilder/index.md) as an
|
|
alternative.
|
|
|
|
To enable Dev Containers in workspaces, configure your template with the Dev Containers
|
|
modules and configurations outlined in this doc.
|
|
|
|
Dev Containers are currently not supported in Windows or macOS workspaces.
|
|
|
|
## Configuration Modes
|
|
|
|
There are two approaches to configuring Dev Containers in Coder:
|
|
|
|
### Manual Configuration
|
|
|
|
Use the [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev
|
|
Containers should be started in your workspace. This approach provides:
|
|
|
|
- Predictable behavior and explicit control
|
|
- Clear template configuration
|
|
- Easier troubleshooting
|
|
- Better for production environments
|
|
|
|
This is the recommended approach for most use cases.
|
|
|
|
### Project Discovery
|
|
|
|
Alternatively, enable automatic discovery of Dev Containers in Git repositories.
|
|
The agent scans for `devcontainer.json` files and surfaces them in the Coder UI.
|
|
See [Environment Variables](#environment-variables) for configuration options.
|
|
|
|
This approach is useful when developers frequently switch between repositories
|
|
or work with many projects, as it reduces template maintenance overhead.
|
|
|
|
## Install the Dev Containers CLI
|
|
|
|
Use the
|
|
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
|
|
to ensure the `@devcontainers/cli` is installed in your workspace:
|
|
|
|
```tf
|
|
module "devcontainers-cli" {
|
|
count = data.coder_workspace.me.start_count
|
|
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
|
agent_id = coder_agent.dev.id
|
|
}
|
|
```
|
|
|
|
Alternatively, install the devcontainer CLI manually in your base image.
|
|
|
|
## Configure Automatic Dev Container Startup
|
|
|
|
The
|
|
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
|
|
resource automatically starts a Dev Container in your workspace, ensuring it's
|
|
ready when you access the workspace:
|
|
|
|
```tf
|
|
resource "coder_devcontainer" "my-repository" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_agent.dev.id
|
|
workspace_folder = "/home/coder/my-repository"
|
|
}
|
|
```
|
|
|
|
The `workspace_folder` attribute must point to a valid project folder containing
|
|
a `devcontainer.json` file. Consider using the
|
|
[`git-clone`](https://registry.coder.com/modules/git-clone) module to ensure
|
|
your repository is cloned and ready for automatic startup.
|
|
|
|
For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
|
|
pointing to a different repository. Each one runs as a separate sub-agent with
|
|
its own terminal and apps in the dashboard.
|
|
|
|
## Enable Dev Containers Integration
|
|
|
|
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
|
|
You don't need to set any environment variables unless you want to change the
|
|
default behavior.
|
|
|
|
If you need to explicitly disable Dev Containers, set the
|
|
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:
|
|
|
|
```tf
|
|
resource "docker_container" "workspace" {
|
|
count = data.coder_workspace.me.start_count
|
|
image = "codercom/oss-dogfood:latest"
|
|
env = [
|
|
"CODER_AGENT_DEVCONTAINERS_ENABLE=false", # Explicitly disable
|
|
# ... Other environment variables.
|
|
]
|
|
# ... Other container configuration.
|
|
}
|
|
```
|
|
|
|
See the [Environment Variables](#environment-variables) section below for more
|
|
details on available configuration options.
|
|
|
|
## Environment Variables
|
|
|
|
The following environment variables control Dev Container behavior in your
|
|
workspace. Both `CODER_AGENT_DEVCONTAINERS_ENABLE` and
|
|
`CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are **enabled by default**,
|
|
so you typically don't need to set them unless you want to explicitly disable
|
|
the feature.
|
|
|
|
### CODER_AGENT_DEVCONTAINERS_ENABLE
|
|
|
|
**Default: `true`** • **Added in: v2.24.0**
|
|
|
|
Enables the Dev Containers integration in the Coder agent.
|
|
|
|
The Dev Containers feature is enabled by default. You can explicitly disable it
|
|
by setting this to `false`.
|
|
|
|
### CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE
|
|
|
|
**Default: `true`** • **Added in: v2.25.0**
|
|
|
|
Enables automatic discovery of Dev Containers in Git repositories.
|
|
|
|
When enabled, the agent scans the configured working directory (set via the
|
|
`directory` attribute in `coder_agent`, typically the user's home directory) for
|
|
Git repositories. If the directory itself is a Git repository, it searches that
|
|
project. Otherwise, it searches immediate subdirectories for Git repositories.
|
|
|
|
For each repository found, the agent looks for `devcontainer.json` files in the
|
|
[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
|
|
and surfaces discovered Dev Containers in the Coder UI. Discovery respects
|
|
`.gitignore` patterns.
|
|
|
|
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
|
|
|
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
|
|
|
|
**Default: `false`** • **Added in: v2.25.0**
|
|
|
|
Automatically starts Dev Containers discovered via project discovery.
|
|
|
|
When enabled, discovered Dev Containers will be automatically built and started
|
|
during workspace initialization. This only applies to Dev Containers found via
|
|
project discovery. Dev Containers defined with the `coder_devcontainer` resource
|
|
always auto-start regardless of this setting.
|
|
|
|
## Attach Resources to Dev Containers
|
|
|
|
You can attach
|
|
[`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app),
|
|
[`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script),
|
|
and [`coder_env`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/env)
|
|
resources to a `coder_devcontainer` by referencing its `subagent_id` attribute
|
|
as the `agent_id`:
|
|
|
|
```tf
|
|
resource "coder_devcontainer" "my-repository" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_agent.dev.id
|
|
workspace_folder = "/home/coder/my-repository"
|
|
}
|
|
|
|
resource "coder_app" "code-server" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_devcontainer.my-repository[0].subagent_id
|
|
# ...
|
|
}
|
|
|
|
resource "coder_script" "dev-setup" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_devcontainer.my-repository[0].subagent_id
|
|
# ...
|
|
}
|
|
|
|
resource "coder_env" "my-var" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_devcontainer.my-repository[0].subagent_id
|
|
# ...
|
|
}
|
|
```
|
|
|
|
This also enables using [Coder registry](https://registry.coder.com) modules
|
|
that depend on these resources inside dev containers, by passing the
|
|
`subagent_id` as the module's `agent_id`.
|
|
|
|
### Terraform-managed dev containers
|
|
|
|
When a `coder_devcontainer` has any `coder_app`, `coder_script`, or `coder_env`
|
|
resource attached, it becomes a **terraform-managed** dev container. This
|
|
changes how Coder handles the sub-agent:
|
|
|
|
- The sub-agent is pre-defined during Terraform provisioning rather than created
|
|
dynamically.
|
|
- On dev container configuration changes, Coder updates the sub-agent in-place
|
|
instead of deleting and recreating it.
|
|
|
|
### Interaction with devcontainer.json customizations
|
|
|
|
Terraform-defined resources and
|
|
[`devcontainer.json` customizations](../../../user-guides/devcontainers/customizing-dev-containers.md)
|
|
work together with some limitations. The `displayApps` settings from
|
|
`devcontainer.json` are applied to terraform-managed dev containers, so you can
|
|
control built-in app visibility (e.g., hide VS Code Insiders) via
|
|
`devcontainer.json` even when using Terraform resources.
|
|
|
|
However, custom `apps` defined in `devcontainer.json` are **not applied** to
|
|
terraform-managed dev containers. If you need custom apps, define them as
|
|
`coder_app` resources in Terraform instead.
|
|
|
|
## Per-Container Customizations
|
|
|
|
Developers can customize individual dev containers using the `customizations.coder`
|
|
block in their `devcontainer.json` file. Available options include:
|
|
|
|
- `ignore` — Hide a dev container from Coder completely
|
|
- `autoStart` — Control whether the container starts automatically (requires
|
|
`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
|
|
- `name` — Set a custom agent name
|
|
- `displayApps` — Control which built-in apps appear
|
|
- `apps` — Define custom applications
|
|
|
|
For the full reference, see
|
|
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
|
|
|
## Complete Template Example
|
|
|
|
Here's a simplified template example that uses Dev Containers with manual
|
|
configuration:
|
|
|
|
```tf
|
|
terraform {
|
|
required_providers {
|
|
coder = { source = "coder/coder" }
|
|
docker = { source = "kreuzwerker/docker" }
|
|
}
|
|
}
|
|
|
|
provider "coder" {}
|
|
data "coder_workspace" "me" {}
|
|
data "coder_workspace_owner" "me" {}
|
|
|
|
resource "coder_agent" "dev" {
|
|
arch = "amd64"
|
|
os = "linux"
|
|
startup_script_behavior = "blocking"
|
|
startup_script = "sudo service docker start"
|
|
shutdown_script = "sudo service docker stop"
|
|
# ...
|
|
}
|
|
|
|
module "devcontainers-cli" {
|
|
count = data.coder_workspace.me.start_count
|
|
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
|
agent_id = coder_agent.dev.id
|
|
}
|
|
|
|
resource "coder_devcontainer" "my-repository" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_agent.dev.id
|
|
workspace_folder = "/home/coder/my-repository"
|
|
}
|
|
|
|
# Attaching resources to dev containers is optional. By attaching
|
|
# this resource to the dev container, we are changing how the dev
|
|
# container will be treated by Coder. This limits the ability to
|
|
# customize the injected agent via the devcontainer.json file.
|
|
resource "coder_env" "env" {
|
|
count = data.coder_workspace.me.start_count
|
|
agent_id = coder_devcontainer.my-repository[0].subagent_id
|
|
name = "MY_VAR"
|
|
value = "my-value"
|
|
}
|
|
```
|
|
|
|
### Alternative: Project Discovery with Autostart
|
|
|
|
By default, discovered containers appear in the dashboard but developers must
|
|
manually start them. To have them start automatically, enable autostart:
|
|
|
|
```tf
|
|
resource "docker_container" "workspace" {
|
|
count = data.coder_workspace.me.start_count
|
|
image = "codercom/oss-dogfood:latest"
|
|
env = [
|
|
# Project discovery is enabled by default, but autostart is not.
|
|
# Enable autostart to automatically build and start discovered containers:
|
|
"CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true",
|
|
# ... Other environment variables.
|
|
]
|
|
# ... Other container configuration.
|
|
}
|
|
```
|
|
|
|
With autostart enabled:
|
|
|
|
- Discovered containers automatically build and start during workspace
|
|
initialization
|
|
- The `coder_devcontainer` resource is not required
|
|
- Developers can work with multiple projects seamlessly
|
|
|
|
> [!NOTE]
|
|
>
|
|
> When using project discovery, you still need to install the devcontainers CLI
|
|
> using the module or in your base image.
|
|
|
|
## Example Template
|
|
|
|
The [Docker (Dev Containers)](../../../../examples/templates/docker-devcontainer)
|
|
starter template demonstrates Dev Containers integration using Docker-in-Docker.
|
|
It includes the `devcontainers-cli` module, `git-clone` module, and the
|
|
`coder_devcontainer` resource.
|
|
|
|
## Next Steps
|
|
|
|
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
|
|
- [Customizing Dev Containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
|
|
- [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
|
|
- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)
|