mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
docs: update dev containers documentation to reflect GA status (#20847)
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 👩
This commit is contained in:
Danielle Maywood
@@ -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)
|
||||
|
||||
@@ -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)
|
||||
|
||||
Reference in New Issue
Block a user