Skip to content

Commit 97bc7eb

Browse files
mafredrimafredri
authored
docs: restructure dev container documentation (#21157)
Dev container admin docs were scattered across two locations: the Docker-based integration under extending-templates/ and Envbuilder under managing-templates/. There was no landing page explaining that two approaches exist or helping admins choose between them. This moves everything under admin/integrations/devcontainers/ with a decision guide at the top. Dev containers are an integration with the dev container specification, so integrations/ is a natural fit alongside JFrog, Vault, etc. Stub pages remain at the original locations for discoverability. New structure: admin/integrations/devcontainers/ ├── index.md # Landing page + decision guide ├── integration.md # Docker-based dev containers └── envbuilder/ ├── index.md ├── add-envbuilder.md ├── envbuilder-security-caching.md └── envbuilder-releases-known-issues.md Refs #21080
1 parent 244e6ca commit 97bc7eb

File tree

16 files changed

+447
-426
lines changed

16 files changed

+447
-426
lines changed

‎docs/admin/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
5252
### Development containers (dev containers)
5353

5454
- A
55-
[Development Container](./templates/extending-templates/devcontainers.md)
55+
[Development Container](./integrations/devcontainers/index.md)
5656
is an open-source specification for defining development environments (called
5757
dev containers). It is generally stored in VCS alongside associated source
5858
code. It can reference an existing base image, or a custom Dockerfile that

docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md renamed to docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
A Coder administrator adds an Envbuilder-compatible template to Coder. This
44
allows the template to prompt the developer for their dev container repository's
5-
URL as a [parameter](../../extending-templates/parameters.md) when they create
5+
URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create
66
their workspace. Envbuilder clones the repo and builds a container from the
77
`devcontainer.json` specified in the repo.
88

@@ -127,7 +127,7 @@ their development environments:
127127
| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/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. |
128128

129129
Your template can prompt the user for a repo URL with
130-
[parameters](../../extending-templates/parameters.md):
130+
[parameters](../../../templates/extending-templates/parameters.md):
131131

132132
![Dev container parameter screen](../../../../images/templates/devcontainers.png)
133133

docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md renamed to docs/admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues.md

File renamed without changes.

docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md renamed to docs/admin/integrations/devcontainers/envbuilder/envbuilder-security-caching.md

File renamed without changes.

‎docs/admin/integrations/devcontainers/envbuilder/index.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# Envbuilder
2+
3+
Envbuilder is an open-source tool that builds development environments from
4+
[dev container](https://containers.dev/implementors/spec/) configuration files.
5+
Unlike the [Dev Containers integration](../integration.md),
6+
Envbuilder transforms the workspace image itself rather than running containers
7+
inside the workspace.
8+
9+
> [!NOTE]
10+
>
11+
> For most use cases, we recommend the
12+
> [Dev Containers integration](../integration.md),
13+
> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
14+
> alternative for environments where Docker is not available or for
15+
> administrator-controlled dev container workflows.
16+
17+
Dev containers provide developers with increased autonomy and control over their
18+
Coder cloud development environments.
19+
20+
By using dev containers, developers can customize their workspaces with tools
21+
pre-approved by platform teams in registries like
22+
[JFrog Artifactory](../../jfrog-artifactory.md). This simplifies
23+
workflows, reduces the need for tickets and approvals, and promotes greater
24+
independence for developers.
25+
26+
## Prerequisites
27+
28+
An administrator should construct or choose a base image and create a template
29+
that includes a `devcontainer_builder` image before a developer team configures
30+
dev containers.
31+
32+
## Devcontainer Features
33+
34+
[Dev container Features](https://containers.dev/implementors/features/) allow
35+
owners of a project to specify self-contained units of code and runtime
36+
configuration that can be composed together on top of an existing base image.
37+
This is a good place to install project-specific tools, such as
38+
language-specific runtimes and compilers.
39+
40+
## Coder Envbuilder
41+
42+
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
43+
maintained by Coder that runs dev containers via Coder templates and your
44+
underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
45+
46+
It is independently packaged and versioned from the centralized Coder
47+
open-source project. This means that Envbuilder can be used with Coder, but it
48+
is not required. It also means that dev container builds can scale independently
49+
of the Coder control plane and even run within a CI/CD pipeline.
50+
51+
## Next steps
52+
53+
- [Add an Envbuilder template](./add-envbuilder.md)

‎docs/admin/integrations/devcontainers/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Dev Containers
2+
3+
Dev containers allow developers to define their development environment
4+
as code using the [Dev Container specification](https://containers.dev/).
5+
Configuration lives in a `devcontainer.json` file alongside source code,
6+
enabling consistent, reproducible environments.
7+
8+
By adopting dev containers, organizations can:
9+
10+
- **Standardize environments**: Eliminate "works on my machine" issues while
11+
still allowing developers to customize their tools within approved boundaries.
12+
- **Scale efficiently**: Let developers maintain their own environment
13+
definitions, reducing the burden on platform teams.
14+
- **Improve security**: Use hardened base images and controlled package
15+
registries to enforce security policies while enabling developer self-service.
16+
17+
Coder supports two approaches for running dev containers. Choose based on your
18+
infrastructure and workflow requirements.
19+
20+
## Dev Containers Integration
21+
22+
The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker
23+
to run containers inside your workspace. This is the recommended approach for
24+
most use cases.
25+
26+
**Best for:**
27+
28+
- Workspaces with Docker available (Docker-in-Docker or mounted socket)
29+
- Dev container management in the Coder dashboard (discovery, status, rebuild)
30+
- Multiple dev containers per workspace
31+
32+
[Configure Dev Containers Integration](./integration.md)
33+
34+
For user documentation, see the
35+
[Dev Containers user guide](../../../user-guides/devcontainers/index.md).
36+
37+
## Envbuilder
38+
39+
Envbuilder transforms the workspace image itself from a `devcontainer.json`,
40+
rather than running containers inside the workspace. It does not require
41+
a Docker daemon.
42+
43+
**Best for:**
44+
45+
- Environments where Docker is unavailable or restricted
46+
- Infrastructure-level control over image builds, caching, and security scanning
47+
- Kubernetes-native deployments without privileged containers
48+
49+
[Configure Envbuilder](./envbuilder/index.md)

‎docs/admin/integrations/devcontainers/integration.md‎

Lines changed: 266 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,266 @@
1+
# Configure a template for Dev Containers
2+
3+
> [!NOTE]
4+
> For environments without Docker, see [Envbuilder](./envbuilder/index.md) as an alternative.
5+
6+
To enable Dev Containers in workspaces, configure your template with the Dev Containers
7+
modules and configurations outlined in this doc.
8+
9+
> [!NOTE]
10+
>
11+
> Dev Containers require a **Linux or macOS workspace**. Windows is not supported.
12+
13+
## Configuration Modes
14+
15+
There are two approaches to configuring Dev Containers in Coder:
16+
17+
### Manual Configuration
18+
19+
Use the [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) Terraform resource to explicitly define which Dev
20+
Containers should be started in your workspace. This approach provides:
21+
22+
- Predictable behavior and explicit control
23+
- Clear template configuration
24+
- Easier troubleshooting
25+
- Better for production environments
26+
27+
This is the recommended approach for most use cases.
28+
29+
### Project Discovery
30+
31+
Alternatively, enable automatic discovery of Dev Containers in Git repositories.
32+
The agent scans for `devcontainer.json` files and surfaces them in the Coder UI.
33+
See [Environment Variables](#environment-variables) for configuration options.
34+
35+
## Install the Dev Containers CLI
36+
37+
Use the
38+
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
39+
to ensure the `@devcontainers/cli` is installed in your workspace:
40+
41+
```terraform
42+
module "devcontainers-cli" {
43+
count = data.coder_workspace.me.start_count
44+
source = "registry.coder.com/coder/devcontainers-cli/coder"
45+
agent_id = coder_agent.dev.id
46+
}
47+
```
48+
49+
Alternatively, install the devcontainer CLI manually in your base image.
50+
51+
## Configure Automatic Dev Container Startup
52+
53+
The
54+
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
55+
resource automatically starts a Dev Container in your workspace, ensuring it's
56+
ready when you access the workspace:
57+
58+
```terraform
59+
resource "coder_devcontainer" "my-repository" {
60+
count = data.coder_workspace.me.start_count
61+
agent_id = coder_agent.dev.id
62+
workspace_folder = "/home/coder/my-repository"
63+
}
64+
```
65+
66+
> [!NOTE]
67+
>
68+
> The `workspace_folder` attribute must specify the location of the dev
69+
> container's workspace and should point to a valid project folder containing a
70+
> `devcontainer.json` file.
71+
72+
<!-- nolint:MD028/no-blanks-blockquote -->
73+
74+
> [!TIP]
75+
>
76+
> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
77+
> module to ensure your repository is cloned into the workspace folder and ready
78+
> for automatic startup.
79+
80+
For multi-repo workspaces, define multiple `coder_devcontainer` resources, each
81+
pointing to a different repository. Each one runs as a separate sub-agent with
82+
its own terminal and apps in the dashboard.
83+
84+
## Enable Dev Containers Integration
85+
86+
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
87+
You don't need to set any environment variables unless you want to change the
88+
default behavior.
89+
90+
If you need to explicitly disable Dev Containers, set the
91+
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `false`:
92+
93+
```terraform
94+
resource "docker_container" "workspace" {
95+
count = data.coder_workspace.me.start_count
96+
image = "codercom/oss-dogfood:latest"
97+
env = [
98+
"CODER_AGENT_DEVCONTAINERS_ENABLE=false", # Explicitly disable
99+
# ... Other environment variables.
100+
]
101+
# ... Other container configuration.
102+
}
103+
```
104+
105+
See the [Environment Variables](#environment-variables) section below for more
106+
details on available configuration options.
107+
108+
## Environment Variables
109+
110+
The following environment variables control Dev Container behavior in your
111+
workspace. Both `CODER_AGENT_DEVCONTAINERS_ENABLE` and
112+
`CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE` are **enabled by default**,
113+
so you typically don't need to set them unless you want to explicitly disable
114+
the feature.
115+
116+
### CODER_AGENT_DEVCONTAINERS_ENABLE
117+
118+
**Default: `true`** • **Added in: v2.24.0**
119+
120+
Enables the Dev Containers integration in the Coder agent.
121+
122+
The Dev Containers feature is enabled by default. You can explicitly disable it
123+
by setting this to `false`.
124+
125+
### CODER_AGENT_DEVCONTAINERS_PROJECT_DISCOVERY_ENABLE
126+
127+
**Default: `true`** • **Added in: v2.25.0**
128+
129+
Enables automatic discovery of Dev Containers in Git repositories.
130+
131+
When enabled, the agent scans the configured working directory (set via the
132+
`directory` attribute in `coder_agent`, typically the user's home directory) for
133+
Git repositories. If the directory itself is a Git repository, it searches that
134+
project. Otherwise, it searches immediate subdirectories for Git repositories.
135+
136+
For each repository found, the agent looks for `devcontainer.json` files in the
137+
[standard locations](../../../user-guides/devcontainers/index.md#add-a-devcontainerjson)
138+
and surfaces discovered Dev Containers in the Coder UI. Discovery respects
139+
`.gitignore` patterns.
140+
141+
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
142+
143+
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
144+
145+
**Default: `false`** • **Added in: v2.25.0**
146+
147+
Automatically starts Dev Containers discovered via project discovery.
148+
149+
When enabled, discovered Dev Containers will be automatically built and started
150+
during workspace initialization. This only applies to Dev Containers found via
151+
project discovery. Dev Containers defined with the `coder_devcontainer` resource
152+
always auto-start regardless of this setting.
153+
154+
## Per-Container Customizations
155+
156+
> [!NOTE]
157+
>
158+
> Dev container sub-agents are created dynamically after workspace provisioning,
159+
> so Terraform resources like
160+
> [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)
161+
> and [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
162+
> cannot currently be attached to them. Modules from the
163+
> [Coder registry](https://registry.coder.com) that depend on these resources
164+
> are also not currently supported for sub-agents.
165+
>
166+
> To add tools to dev containers, use
167+
> [dev container features](../../../user-guides/devcontainers/working-with-dev-containers.md#dev-container-features).
168+
> For Coder-specific apps, use the
169+
> [`apps` customization](../../../user-guides/devcontainers/customizing-dev-containers.md#custom-apps).
170+
171+
Developers can customize individual dev containers using the `customizations.coder`
172+
block in their `devcontainer.json` file. Available options include:
173+
174+
- `ignore` — Hide a dev container from Coder completely
175+
- `autoStart` — Control whether the container starts automatically (requires
176+
`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` to be enabled)
177+
- `name` — Set a custom agent name
178+
- `displayApps` — Control which built-in apps appear
179+
- `apps` — Define custom applications
180+
181+
For the full reference, see
182+
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
183+
184+
## Complete Template Example
185+
186+
Here's a simplified template example that uses Dev Containers with manual
187+
configuration:
188+
189+
```terraform
190+
terraform {
191+
required_providers {
192+
coder = { source = "coder/coder" }
193+
docker = { source = "kreuzwerker/docker" }
194+
}
195+
}
196+
197+
provider "coder" {}
198+
data "coder_workspace" "me" {}
199+
data "coder_workspace_owner" "me" {}
200+
201+
resource "coder_agent" "dev" {
202+
arch = "amd64"
203+
os = "linux"
204+
startup_script_behavior = "blocking"
205+
startup_script = "sudo service docker start"
206+
shutdown_script = "sudo service docker stop"
207+
# ...
208+
}
209+
210+
module "devcontainers-cli" {
211+
count = data.coder_workspace.me.start_count
212+
source = "registry.coder.com/coder/devcontainers-cli/coder"
213+
agent_id = coder_agent.dev.id
214+
}
215+
216+
resource "coder_devcontainer" "my-repository" {
217+
count = data.coder_workspace.me.start_count
218+
agent_id = coder_agent.dev.id
219+
workspace_folder = "/home/coder/my-repository"
220+
}
221+
```
222+
223+
### Alternative: Project Discovery with Autostart
224+
225+
By default, discovered containers appear in the dashboard but developers must
226+
manually start them. To have them start automatically, enable autostart:
227+
228+
```terraform
229+
resource "docker_container" "workspace" {
230+
count = data.coder_workspace.me.start_count
231+
image = "codercom/oss-dogfood:latest"
232+
env = [
233+
# Project discovery is enabled by default, but autostart is not.
234+
# Enable autostart to automatically build and start discovered containers:
235+
"CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true",
236+
# ... Other environment variables.
237+
]
238+
# ... Other container configuration.
239+
}
240+
```
241+
242+
With autostart enabled:
243+
244+
- Discovered containers automatically build and start during workspace
245+
initialization
246+
- The `coder_devcontainer` resource is not required
247+
- Developers can work with multiple projects seamlessly
248+
249+
> [!NOTE]
250+
>
251+
> When using project discovery, you still need to install the devcontainers CLI
252+
> using the module or in your base image.
253+
254+
## Example Template
255+
256+
The [Docker (Dev Containers)](https://github.com/coder/coder/tree/main/examples/templates/docker-devcontainer)
257+
starter template demonstrates Dev Containers integration using Docker-in-Docker.
258+
It includes the `devcontainers-cli` module, `git-clone` module, and the
259+
`coder_devcontainer` resource.
260+
261+
## Next Steps
262+
263+
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
264+
- [Customizing Dev Containers](../../../user-guides/devcontainers/customizing-dev-containers.md)
265+
- [Working with Dev Containers](../../../user-guides/devcontainers/working-with-dev-containers.md)
266+
- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md)

0 commit comments

Comments
 (0)