docs: rewrite dev containers documentation for GA (#21080)

mafredri · web-flow · commit 61beb7bfa8b3 · 2025-12-05T19:42:16.000+02:00
docs: rewrite dev containers documentation for GA Corrects inaccuracies in SSH examples (deprecated `--container` flag), port forwarding (native sub-agent forwarding is primary), and prerequisites (dev containers are on by default). Fixes template descriptions: docker-devcontainer uses native Dev Containers while AWS/Kubernetes templates use Envbuilder. Renames admin docs folder from `devcontainers/` to `envbuilder/` to reflect actual content. Adds customization guide documenting agent naming, display apps, custom apps, and variable interpolation. Documents multi-repo workspace support and adds note about Terraform module limitations with sub-agents. Fixes module registry URLs. Refs #18907
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
@@ -0,0 +1,3 @@
+{
+	"ignores": ["PLAN.md"],
+}
diff --git a/docs/_redirects b/docs/_redirects
@@ -4,3 +4,10 @@
 # Redirect old offline anchor fragments to new airgap anchors
 /install/offline#offline-docs /install/airgap#airgap-docs 301
 /install/offline#offline-container-images /install/airgap#airgap-container-images 301
+
+# Redirect old devcontainers folder to envbuilder
+/admin/templates/managing-templates/devcontainers /admin/templates/managing-templates/envbuilder 301
+/admin/templates/managing-templates/devcontainers/index /admin/templates/managing-templates/envbuilder 301
+/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/templates/managing-templates/envbuilder/add-envbuilder 301
+/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/templates/managing-templates/envbuilder/envbuilder-security-caching 301
+/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues 301
diff --git a/docs/about/contributing/templates.md b/docs/about/contributing/templates.md
@@ -510,9 +510,9 @@ resource "kubernetes_pod" "workspace" {
 ## Get help
 
 - **Examples**: Review real-world examples from the [official Coder templates](https://registry.coder.com/contributors/coder?tab=templates):
-  - [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with devcontainer support
-  - [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Envbuilder containers with dev container support
-  - [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Envbuilder pods on Kubernetes
+  - [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with Envbuilder
+  - [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Docker-in-Docker with Dev Containers integration
+  - [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Kubernetes pods with Envbuilder
   - [Docker Containers](https://registry.coder.com/templates/docker) - Basic Docker container workspaces
   - [AWS EC2 (Linux)](https://registry.coder.com/templates/aws-linux) - AWS EC2 VMs for Linux development
   - [Google Compute Engine (Linux)](https://registry.coder.com/templates/gcp-vm-container) - GCP VM instances
diff --git a/docs/admin/index.md b/docs/admin/index.md
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
 ### Development containers (dev containers)
 
 - A
-  [Development Container](./templates/managing-templates/devcontainers/index.md)
+  [Development Container](./templates/extending-templates/devcontainers.md)
   is an open-source specification for defining development environments (called
   dev containers). It is generally stored in VCS alongside associated source
   code. It can reference an existing base image, or a custom Dockerfile that
diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md
@@ -25,7 +25,9 @@ This is the recommended approach for most use cases.
 
 ### Project Discovery
 
-Enable automatic discovery of Dev Containers in Git repositories. Project discovery automatically scans Git repositories for `.devcontainer/devcontainer.json` or `.devcontainer.json` files and surfaces them in the Coder UI. See the [Environment Variables](#environment-variables) section for detailed configuration options.
+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.
 
 ## Install the Dev Containers CLI
 
@@ -36,7 +38,7 @@ to ensure the `@devcontainers/cli` is installed in your workspace:
 ```terraform
 module "devcontainers-cli" {
   count    = data.coder_workspace.me.start_count
-  source   = "dev.registry.coder.com/modules/devcontainers-cli/coder"
+  source   = "registry.coder.com/coder/devcontainers-cli/coder"
   agent_id = coder_agent.dev.id
 }
 ```
@@ -72,6 +74,10 @@ resource "coder_devcontainer" "my-repository" {
 > module to ensure your repository is cloned into the workspace folder 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.
@@ -119,15 +125,17 @@ by setting this to `false`.
 
 Enables automatic discovery of Dev Containers in Git repositories.
 
-When enabled, the agent will:
+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.
 
-- Scan the agent directory for Git repositories
-- Look for `.devcontainer/devcontainer.json` or `.devcontainer.json` files
-- Surface discovered Dev Containers automatically in the Coder UI
-- Respect `.gitignore` patterns during discovery
+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.
 
-You can disable automatic discovery by setting this to `false` if you prefer to
-use only the `coder_devcontainer` resource for explicit configuration.
+Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
 
 ### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
 
@@ -142,67 +150,33 @@ always auto-start regardless of this setting.
 
 ## Per-Container Customizations
 
-Individual Dev Containers can be customized using the `customizations.coder` block
-in your `devcontainer.json` file. These customizations allow you to control
-container-specific behavior without modifying your template.
-
-### Ignore Specific Containers
-
-Use the `ignore` option to hide a Dev Container from Coder completely:
-
-```json
-{
-  "name": "My Dev Container",
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
-  "customizations": {
-    "coder": {
-      "ignore": true
-    }
-  }
-}
-```
-
-When `ignore` is set to `true`:
-
-- The Dev Container won't appear in the Coder UI
-- Coder won't manage or monitor the container
-
-This is useful when you have Dev Containers in your repository that you don't
-want Coder to manage.
-
-### Per-Container Auto-Start
-
-Control whether individual Dev Containers should auto-start using the
-`autoStart` option:
-
-```json
-{
-  "name": "My Dev Container",
-  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
-  "customizations": {
-    "coder": {
-      "autoStart": true
-    }
-  }
-}
-```
-
-**Important**: The `autoStart` option only applies when global auto-start is
-enabled via `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE=true`. If
-the global setting is disabled, containers won't auto-start regardless of this
-setting.
-
-When `autoStart` is set to `true`:
+> [!NOTE]
+>
+> Dev container sub-agents are created dynamically after workspace provisioning,
+> so Terraform resources like
+> [`coder_script`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/script)
+> and [`coder_app`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/app)
+> cannot currently be attached to them. Modules from the
+> [Coder registry](https://registry.coder.com) that depend on these resources
+> are also not currently supported for sub-agents.
+>
+> To add tools to dev containers, use
+> [dev container features](../../../user-guides/devcontainers/working-with-dev-containers.md#dev-container-features).
+> For Coder-specific apps, use the
+> [`apps` customization](../../../user-guides/devcontainers/customizing-dev-containers.md#custom-apps).
 
-- The Dev Container automatically builds and starts during workspace
-  initialization
-- Works on a per-container basis (you can enable it for some containers but not
-  others)
+Developers can customize individual dev containers using the `customizations.coder`
+block in their `devcontainer.json` file. Available options include:
 
-When `autoStart` is set to `false` or omitted:
+- `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
 
-- The Dev Container is discovered and shown in the UI
-- Users must manually start it via the UI
+For the full reference, see
+[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
 
 ## Complete Template Example
 
@@ -232,7 +206,7 @@ resource "coder_agent" "dev" {
 
 module "devcontainers-cli" {
   count    = data.coder_workspace.me.start_count
-  source   = "dev.registry.coder.com/modules/devcontainers-cli/coder"
+  source   = "registry.coder.com/coder/devcontainers-cli/coder"
   agent_id = coder_agent.dev.id
 }
 
@@ -243,9 +217,10 @@ resource "coder_devcontainer" "my-repository" {
 }
 ```
 
-### Alternative: Project Discovery Mode
+### Alternative: Project Discovery with Autostart
 
-You can enable automatic starting of discovered Dev Containers:
+By default, discovered containers appear in the dashboard but developers must
+manually start them. To have them start automatically, enable autostart:
 
 ```terraform
 resource "docker_container" "workspace" {
@@ -261,20 +236,28 @@ resource "docker_container" "workspace" {
 }
 ```
 
-With this configuration:
+With autostart enabled:
 
-- Project discovery is enabled (default behavior)
-- Discovered containers are automatically started (via the env var)
-- The `coder_devcontainer` resource is **not** required
+- 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)](https://github.com/coder/coder/tree/main/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)
diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md
@@ -48,11 +48,10 @@ needs of different teams.
 
 - [Image management](./managing-templates/image-management.md): Learn how to
   create and publish images for use within Coder workspaces & templates.
-- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
-  dev containers to allow teams to bring their own tools into Coder workspaces.
-- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our
-  new direct devcontainers integration (distinct from Envbuilder-based
-  approach).
+- [Dev Containers integration](./extending-templates/devcontainers.md): Enable
+  native dev containers support using `@devcontainers/cli` and Docker.
+- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
+  for environments without Docker access.
 - [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
   Configure your template to prevent certain resources from being destroyed
   (e.g. user disks).
diff --git a/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md b/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md
@@ -1,10 +1,9 @@
-# Add a dev container template to Coder
+# Add an Envbuilder template
 
-A Coder administrator adds a dev container-compatible template to Coder
-(Envbuilder). This allows the template to prompt for the developer for their dev
-container repository's URL as a
-[parameter](../../extending-templates/parameters.md) when they create their
-workspace. Envbuilder clones the repo and builds a container from the
+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](../../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
@@ -143,4 +142,4 @@ Lifecycle scripts are managed by project developers.
 
 ## Next steps
 
-- [Dev container security and caching](./devcontainer-security-caching.md)
+- [Envbuilder security and caching](./envbuilder-security-caching.md)
diff --git a/docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md b/docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md
@@ -1,4 +1,4 @@
-# Dev container releases and known issues
+# Envbuilder releases and known issues
 
 ## Release channels
 
diff --git a/docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md b/docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md
@@ -1,4 +1,4 @@
-# Dev container security and caching
+# Envbuilder security and caching
 
 Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
 it with your existing HTTP proxies, firewalls, and artifact managers.
@@ -26,7 +26,7 @@ of caching:
 
   - Caches the entire image, skipping the build process completely (except for
     post-build
-    [lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
+    [lifecycle scripts](./add-envbuilder.md#dev-container-lifecycle-scripts)).
 
 Note that caching requires push access to a registry, and may require approval
 from relevant infrastructure team(s).
@@ -62,5 +62,5 @@ You may also wish to consult a
 
 ## Next steps
 
-- [Dev container releases and known issues](./devcontainer-releases-known-issues.md)
+- [Envbuilder releases and known issues](./envbuilder-releases-known-issues.md)
 - [Dotfiles](../../../../user-guides/workspace-dotfiles.md)
diff --git a/docs/admin/templates/managing-templates/envbuilder/index.md b/docs/admin/templates/managing-templates/envbuilder/index.md
@@ -1,9 +1,18 @@
-# Dev containers
-
-A Development Container is an
-[open-source specification](https://containers.dev/implementors/spec/) for
-defining containerized development environments which are also called
-development containers (dev containers).
+# Envbuilder
+
+Envbuilder is an open-source tool that builds development environments from
+[dev container](https://containers.dev/implementors/spec/) configuration files.
+Unlike the [native Dev Containers integration](../../extending-templates/devcontainers.md),
+Envbuilder transforms the workspace image itself rather than running containers
+inside the workspace.
+
+> [!NOTE]
+>
+> For most use cases, we recommend the
+> [native Dev Containers integration](../../extending-templates/devcontainers.md),
+> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
+> alternative for environments where Docker is not available or for
+> administrator-controlled dev container workflows.
 
 Dev containers provide developers with increased autonomy and control over their
 Coder cloud development environments.
@@ -119,4 +128,4 @@ of the Coder control plane and even run within a CI/CD pipeline.
 
 ## Next steps
 
-- [Add a dev container template](./add-devcontainer.md)
+- [Add an Envbuilder template](./add-envbuilder.md)
diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md
@@ -70,4 +70,5 @@ specific tooling for their projects. The [Dev Container](https://containers.dev)
 specification allows developers to define their projects dependencies within a
 `devcontainer.json` in their Git repository.
 
-- [Learn how to integrate Dev Containers with Coder](./devcontainers/index.md)
+- [Configure a template for Dev Containers](../extending-templates/devcontainers.md) (recommended)
+- [Learn about Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md
@@ -96,5 +96,6 @@ coder templates delete <template-name>
 ## Next steps
 
 - [Image management](./image-management.md)
-- [Devcontainer templates](./devcontainers/index.md)
+- [Dev Containers integration](../extending-templates/devcontainers.md) (recommended)
+- [Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
 - [Change management](./change-management.md)
diff --git a/docs/manifest.json b/docs/manifest.json
diff --git a/docs/user-guides/devcontainers/customizing-dev-containers.md b/docs/user-guides/devcontainers/customizing-dev-containers.md
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
diff --git a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md
diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md
diff --git a/docs/user-guides/index.md b/docs/user-guides/index.md

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "ignores": ["PLAN.md"],`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Dev container releases and known issues`
	`1`	`+# Envbuilder releases and known issues`
`2`	`2`
`3`	`3`	`## Release channels`
`4`	`4`