From 7fd9a450c1e7042d414051cfd93a5e3ffdf9d9a4 Mon Sep 17 00:00:00 2001 From: Danielle Maywood Date: Tue, 25 Nov 2025 11:29:11 +0000 Subject: [PATCH] docs: update dev containers documentation to reflect GA status (#20847) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Updates the dev containers documentation to accurately reflect that the feature is generally available and document all configuration options. Closes https://github.com/coder/internal/issues/1138 --- 🤖 PR was written by Claude Sonnet 4.5 Thinking using [Coder Mux](https://github.com/coder/cmux) and reviewed by a human 👩 --- .../extending-templates/devcontainers.md | 180 ++++++++++++++++-- docs/user-guides/devcontainers/index.md | 78 ++++---- 2 files changed, 200 insertions(+), 58 deletions(-) diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md index d4284bf48e..f3eb4835c5 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -1,8 +1,32 @@ -# Configure a template for dev containers +# Configure a template for Dev Containers -To enable dev containers in workspaces, configure your template with the dev containers +To enable Dev Containers in workspaces, configure your template with the Dev Containers modules and configurations outlined in this doc. +> [!NOTE] +> +> Dev Containers require a **Linux or macOS workspace**. Windows is not supported. + +## 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 + +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. + ## Install the Dev Containers CLI Use the @@ -23,7 +47,7 @@ Alternatively, install the devcontainer CLI manually in your base image. 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 +resource automatically starts a Dev Container in your workspace, ensuring it's ready when you access the workspace: ```terraform @@ -50,30 +74,140 @@ resource "coder_devcontainer" "my-repository" { ## Enable Dev Containers Integration -To enable the dev containers integration in your workspace, you must set the -`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your -workspace container: +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`: ```terraform resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count image = "codercom/oss-dogfood:latest" env = [ - "CODER_AGENT_DEVCONTAINERS_ENABLE=true", + "CODER_AGENT_DEVCONTAINERS_ENABLE=false", # Explicitly disable # ... Other environment variables. ] # ... Other container configuration. } ``` -This environment variable is required for the Coder agent to detect and manage -dev containers. Without it, the agent will not attempt to start or connect to -dev containers even if the `coder_devcontainer` resource is defined. +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 will: + +- 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 + +You can disable automatic discovery by setting this to `false` if you prefer to +use only the `coder_devcontainer` resource for explicit configuration. + +### 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. + +## 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`: + +- 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) + +When `autoStart` is set to `false` or omitted: + +- The Dev Container is discovered and shown in the UI +- Users must manually start it via the UI ## Complete Template Example -Here's a simplified template example that enables the dev containers -integration: +Here's a simplified template example that uses Dev Containers with manual +configuration: ```terraform terraform { @@ -107,18 +241,38 @@ resource "coder_devcontainer" "my-repository" { agent_id = coder_agent.dev.id workspace_folder = "/home/coder/my-repository" } +``` +### Alternative: Project Discovery Mode + +You can enable automatic starting of discovered Dev Containers: + +```terraform resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count image = "codercom/oss-dogfood:latest" env = [ - "CODER_AGENT_DEVCONTAINERS_ENABLE=true", + # 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 this configuration: + +- Project discovery is enabled (default behavior) +- Discovered containers are automatically started (via the env var) +- 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. + ## Next Steps - [Dev Containers Integration](../../../user-guides/devcontainers/index.md) diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md index ed817fe853..04ec15c54b 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -1,81 +1,69 @@ # Dev Containers Integration -> [!NOTE] -> -> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature. -> -> While functional for testing and feedback, it may change significantly before general availability. - -The dev containers integration is an early access feature that enables seamless -creation and management of dev containers in Coder workspaces. This feature -leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and +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) +[Envbuilder-based Dev Containers](../../admin/templates/managing-templates/devcontainers/index.md) offering. ## Prerequisites -- Coder version 2.22.0 or later -- Coder CLI version 2.22.0 or later +- 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 + - Dev Containers integration enabled - A Docker-compatible workspace image - Appropriate permissions to execute Docker commands inside your workspace ## How It Works -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. +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. Dev environments are configured through a standard `devcontainer.json` file, which allows for extensive customization of your development setup. -When a workspace with the dev containers integration starts: +When a workspace with the 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 +1. The integration builds and starts the Dev Container based on the configuration. -1. Your workspace automatically detects the running dev container. +1. Your workspace automatically detects the running Dev Container. ## Features ### Available Now -- Automatic dev container detection from repositories -- Seamless dev container startup during workspace initialization -- Integrated IDE experience in dev containers with VS Code -- Direct service access in dev containers -- Limited SSH access to dev containers +- 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 -### Coming Soon +## Limitations -- Dev container change detection -- On-demand dev container recreation -- Support for automatic port forwarding inside the container -- Full native SSH support to dev containers - -## Limitations during Early Access - -During the early access phase, the dev containers integration has the following -limitations: +The Dev Containers integration has the following limitations: +- **Not supported on Windows** - Changes to the `devcontainer.json` file require manual container recreation -- Automatic port forwarding only works for ports specified in `appPort` -- SSH access requires using the `--container` flag -- Some devcontainer features may not work as expected - -These limitations will be addressed in future updates as the feature matures. + using the rebuild button +- Some Dev Container features may not work as expected ## Comparison with Envbuilder-based Dev Containers -| Feature | Dev Containers (Early Access) | Envbuilder 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 | @@ -84,15 +72,15 @@ These limitations will be addressed in future updates as the feature matures. | 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 +constraints. For additional details on Envbuilder's Dev Container support, see the -[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md). +[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 +- 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 +- 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)