docs(user-guides/devcontainers): rewrite dev containers documentation for GA

mafredri · mafredri · commit 488fb72ed5d6 · 2025-12-03T16:11:12.000Z
The previous documentation had inaccuracies: SSH examples used the deprecated `--container` flag instead of the agent-based pattern (`coder ssh workspace.agent`), port forwarding focused on `appPort` when native forwarding to sub-agents is the primary method, and prerequisites implied users needed to "enable" dev containers when it is on by default. Renamed admin docs folder from `devcontainers/` to `envbuilder/` since it documents Envbuilder specifically, not native dev containers. Added notes pointing to native dev containers as the recommended approach for most use cases. Also fixes module registry URLs that pointed to dev.registry instead of registry.coder.com. 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/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
@@ -36,7 +36,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
 }
 ```
@@ -232,7 +232,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
 }
 
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
@@ -522,24 +522,24 @@
 									"path": "./admin/templates/managing-templates/change-management.md"
 								},
 								{
-									"title": "Dev containers",
-									"description": "Learn about using development containers in templates",
-									"path": "./admin/templates/managing-templates/devcontainers/index.md",
+									"title": "Envbuilder",
+									"description": "Build dev containers using Envbuilder for environments without Docker",
+									"path": "./admin/templates/managing-templates/envbuilder/index.md",
 									"children": [
 										{
-											"title": "Add a dev container template",
-											"description": "How to add a dev container template to Coder",
-											"path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md"
+											"title": "Add an Envbuilder template",
+											"description": "How to add an Envbuilder dev container template to Coder",
+											"path": "./admin/templates/managing-templates/envbuilder/add-envbuilder.md"
 										},
 										{
-											"title": "Dev container security and caching",
-											"description": "Configure dev container authentication and caching",
-											"path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md"
+											"title": "Envbuilder security and caching",
+											"description": "Configure Envbuilder authentication and caching",
+											"path": "./admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md"
 										},
 										{
-											"title": "Dev container releases and known issues",
-											"description": "Dev container releases and known issues",
-											"path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md"
+											"title": "Envbuilder releases and known issues",
+											"description": "Envbuilder releases and known issues",
+											"path": "./admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md"
 										}
 									]
 								},
diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md
@@ -1,87 +1,122 @@
 # Dev Containers Integration
 
-The Dev Containers integration enables seamless creation and management of Dev
-Containers in Coder workspaces. This feature leverages the
+The Dev Containers integration enables seamless creation and management of dev
+containers in Coder workspaces. This feature leverages the
 [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
 [Docker](https://www.docker.com) to provide a streamlined development
 experience.
 
-This implementation is different from the existing
-[Envbuilder-based Dev Containers](../../admin/templates/managing-templates/devcontainers/index.md)
-offering.
-
 ## Prerequisites
 
 - Coder version 2.24.0 or later
-- Coder CLI version 2.24.0 or later
-- **Linux or macOS workspace**, Dev Containers are not supported on Windows
-- A template with:
-  - Dev Containers integration enabled
-  - A Docker-compatible workspace image
-- Appropriate permissions to execute Docker commands inside your workspace
+- Docker available inside your workspace
+- The `@devcontainers/cli` installed in your workspace
+
+Dev Containers integration is enabled by default. Your workspace needs Docker
+(via Docker-in-Docker or a mounted socket) and the devcontainers CLI. Most
+templates with Dev Containers support include both—see
+[Configure a template for dev containers](../../admin/templates/extending-templates/devcontainers.md)
+for setup details.
+
+## Features
+
+- Automatic dev container detection from repositories
+- Seamless container startup during workspace initialization
+- Change detection with dirty state indicators
+- On-demand container rebuild via dashboard button
+- Integrated IDE experience with VS Code
+- Direct SSH access to containers
+- Automatic port detection
+
+## Getting started
+
+### 1. Add a devcontainer.json
+
+Add a `devcontainer.json` file to your repository. This file defines your
+development environment. You can place it in:
+
+- `.devcontainer/devcontainer.json` (recommended)
+- `.devcontainer.json` (root of repository)
+
+Here's a minimal example:
 
-## How It Works
+```json
+{
+  "name": "My Dev Container",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu"
+}
+```
 
-The Dev Containers integration utilizes the `devcontainer` command from
-[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage Dev
-Containers within your Coder workspace.
-This command provides comprehensive functionality for creating, starting, and managing Dev Containers.
+For more configuration options, see the
+[Dev Container specification](https://containers.dev/).
 
-Dev environments are configured through a standard `devcontainer.json` file,
-which allows for extensive customization of your development setup.
+### 2. Start your dev container
 
-When a workspace with the Dev Containers integration starts:
+Coder automatically discovers dev container configurations in your repositories
+and displays them in your workspace dashboard. From there, you can start a dev
+container with a single click.
+
+If your template administrator has configured automatic startup (via the
+`coder_devcontainer` Terraform resource or autostart settings), your dev
+container will build and start automatically when the workspace starts.
+
+### 3. Connect to your dev container
+
+Once running, your dev container appears as a sub-agent in your workspace
+dashboard. You can connect via:
+
+- **Web terminal** in the Coder dashboard
+- **SSH** using `coder ssh <workspace>.<agent>`
+- **VS Code** using the "Open in VS Code Desktop" button
+
+See [Working with dev containers](./working-with-dev-containers.md) for detailed
+connection instructions.
+
+## How it works
+
+The Dev Containers integration uses the `devcontainer` command from
+[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage
+containers within your Coder workspace.
+
+When a workspace with Dev Containers integration starts:
 
 1. The workspace initializes the Docker environment.
-1. The integration detects repositories with a `.devcontainer` directory or a
-   `devcontainer.json` file.
-1. The integration builds and starts the Dev Container based on the
-   configuration.
-1. Your workspace automatically detects the running Dev Container.
+1. The integration detects repositories with dev container configurations.
+1. The integration builds and starts the dev container.
+1. Coder creates a sub-agent for the container, enabling direct access.
 
-## Features
+### Agent naming
 
-### Available Now
+Each dev container gets its own agent name, derived from the workspace folder
+path. For example, a dev container with workspace folder `/home/coder/my-app`
+will have an agent named `my-app`.
 
-- Automatic Dev Container detection from repositories
-- Seamless Dev Container startup during workspace initialization
-- Dev Container change detection and dirty state indicators
-- On-demand Dev Container recreation via rebuild button
-- Integrated IDE experience in Dev Containers with VS Code
-- Direct service access in Dev Containers
-- SSH access to Dev Containers
-- Automatic port detection for container ports
+Agent names are sanitized to contain only lowercase alphanumeric characters and
+hyphens.
 
 ## Limitations
 
-The Dev Containers integration has the following limitations:
-
-- **Not supported on Windows**
-- Changes to the `devcontainer.json` file require manual container recreation
-  using the rebuild button
-- Some Dev Container features may not work as expected
-
-## Comparison with Envbuilder-based Dev Containers
-
-| Feature        | Dev Containers Integration             | Envbuilder Dev Containers                    |
-|----------------|----------------------------------------|----------------------------------------------|
-| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder                           |
-| Target users   | Individual developers                  | Platform teams and administrators            |
-| Configuration  | Standard `devcontainer.json`           | Terraform templates with Envbuilder          |
-| Management     | User-controlled                        | Admin-controlled                             |
-| Requirements   | Docker access in workspace             | Compatible with more restricted environments |
-
-Choose the appropriate solution based on your team's needs and infrastructure
-constraints. For additional details on Envbuilder's Dev Container support, see
-the
-[Envbuilder Dev Container spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
-
-## Next Steps
-
-- Explore the [Dev Container specification](https://containers.dev/) to learn
-  more about advanced configuration options
-- Read about [Dev Container features](https://containers.dev/features) to
-  enhance your development environment
-- Check the
-  [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
-  for IDE-specific features
+- **Linux and macOS only** — Dev Containers are not supported on Windows
+  workspaces
+- Changes to `devcontainer.json` require manual rebuild using the dashboard
+  button
+- The `forwardPorts` property in `devcontainer.json` with `host:port` syntax
+  (e.g., `"db:5432"`) for Docker Compose sidecar containers is not yet
+  supported. For single-container dev containers, use `coder port-forward` to
+  access ports directly on the sub-agent.
+- Some advanced dev container features may have limited support
+
+> [!NOTE]
+> If your template uses Envbuilder rather than Docker-based dev containers, see
+> the [Envbuilder documentation](../../admin/templates/managing-templates/envbuilder/index.md).
+
+## Next steps
+
+- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
+  integration, and port forwarding
+- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
+  Diagnose common issues
+- [Dev Container specification](https://containers.dev/) — Advanced
+  configuration options
+- [Dev Container features](https://containers.dev/features) — Enhance your
+  environment with pre-built tools
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`