Compare commits
6 Commits
devtools/0
...
phorcys/re
| Author | SHA1 | Date | |
|---|---|---|---|
|
885201bc1b | ||
|
|
089a1d6b25 | ||
|
|
455e711e4d | ||
|
|
65e83992fe | ||
|
|
50e672e480 | ||
|
|
26205e5850 |
@@ -1,11 +1,11 @@
|
||||
# Dev Containers
|
||||
|
||||
Dev containers allow developers to define their development environment
|
||||
Dev Containers allow developers to define their development environment
|
||||
as code using the [Dev Container specification](https://containers.dev/).
|
||||
Configuration lives in a `devcontainer.json` file alongside source code,
|
||||
enabling consistent, reproducible environments.
|
||||
|
||||
By adopting dev containers, organizations can:
|
||||
By adopting Dev Containers, organizations can:
|
||||
|
||||
- **Standardize environments**: Eliminate "works on my machine" issues while
|
||||
still allowing developers to customize their tools within approved boundaries.
|
||||
@@ -14,36 +14,129 @@ By adopting dev containers, organizations can:
|
||||
- **Improve security**: Use hardened base images and controlled package
|
||||
registries to enforce security policies while enabling developer self-service.
|
||||
|
||||
Coder supports two approaches for running dev containers. Choose based on your
|
||||
infrastructure and workflow requirements.
|
||||
Coder supports multiple approaches for running Dev Containers. Choose based on
|
||||
your infrastructure and workflow requirements.
|
||||
|
||||
## Dev Containers Integration
|
||||
## Comparison
|
||||
|
||||
The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker
|
||||
to run containers inside your workspace. This is the recommended approach for
|
||||
most use cases.
|
||||
| Method | Dev Container CLI | Envbuilder | CI/CD Pre-built |
|
||||
|-------------------------------------------|--------------------------------------------------------|---------------------------------------|-----------------------------------------------------------|
|
||||
| **Standard Dev Container implementation** | ✅ Yes | ❌ No | ✅ Yes |
|
||||
| **Full Dev Container Spec Support** | ✅ All options | ❌ Limited options | \~ Most options |
|
||||
| **Startup Time** | Build at runtime, faster with caching | Build at runtime, faster with caching | Fast (pre-built) |
|
||||
| **Docker Required** | ❌ Yes | ✅ No | ✅ No |
|
||||
| **Caching** | More difficult | ✅ Yes | ✅ Yes |
|
||||
| **Repo Discovery** | ✅ Yes | ❌ No | ❌ No |
|
||||
| **Custom Apps in-spec** | ✅ Via spec args | ❌ No | ❌ No |
|
||||
| **Debugging** | Easy | Very difficult | Moderate |
|
||||
| **Versioning** | \~ Via spec, or template | \~ Via spec, or template | ✅ Image tags |
|
||||
| **Testing Pipeline** | \~ Via CLI in CI/CD | \~ Via CLI in CI/CD | ✅ Yes, via the same pipeline |
|
||||
| **Feedback Loop** | ✅ Fast | ✅ Fast | Slow (build, and then test) |
|
||||
| **Maintenance Status** | ✅ Active | ⚠️ Maintenance mode | ✅ Active |
|
||||
| **Best For** | Dev flexibility, rapid iteration, feature completeness | Restricted environments | Controlled and centralized releases, less dev flexibility |
|
||||
|
||||
## Dev Container CLI
|
||||
|
||||
The Dev Container CLI integration uses the standard `@devcontainers/cli` and Docker to run
|
||||
Dev Containers inside your workspace. This is the recommended approach for most use
|
||||
cases and provides the most complete Dev Container experience.
|
||||
|
||||
Uses the
|
||||
[devcontainers-cli module](https://registry.coder.com/modules/devcontainers-cli),
|
||||
the `coder_devcontainer` Terraform resource, and
|
||||
`CODER_AGENT_DEVCONTAINERS_ENABLE=true`.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Standard Dev Container implementation via Microsoft's official `@devcontainers/cli` package.
|
||||
- Supports all Dev Container configuration options.
|
||||
- Supports custom arguments in the Dev Container spec for defining custom apps
|
||||
without needing template changes.
|
||||
- Supports discovery of repos with Dev Containers in them.
|
||||
- Easier to debug, since you have access to the outer container.
|
||||
|
||||
**Cons / Requirements:**
|
||||
|
||||
- Requires Docker in workspaces. This does not necessarily mean Docker-in-Docker
|
||||
or a specific Kubernetes runtime — you could use Rootless Podman or a
|
||||
privileged sidecar.
|
||||
- Caching is more difficult than with Envbuilder or CI/CD pre-built approaches.
|
||||
|
||||
**Best for:**
|
||||
|
||||
- Workspaces with Docker available (Docker-in-Docker or mounted socket)
|
||||
- Dev container management in the Coder dashboard (discovery, status, rebuild)
|
||||
- Multiple dev containers per workspace
|
||||
- Dev flexibility, rapid iteration, and feature completeness.
|
||||
- Workspaces with Docker available (Docker-in-Docker or mounted socket).
|
||||
- Dev Container management in the Coder dashboard (discovery, status, rebuild).
|
||||
- Multiple Dev Containers per workspace.
|
||||
|
||||
[Configure Dev Containers Integration](./integration.md)
|
||||
See the [Dev Containers Integration](./integration.md) page for instructions.
|
||||
|
||||
For user documentation, see the
|
||||
[Dev Containers user guide](../../../user-guides/devcontainers/index.md).
|
||||
|
||||
## Envbuilder
|
||||
|
||||
Envbuilder transforms the workspace image itself from a `devcontainer.json`,
|
||||
rather than running containers inside the workspace. It does not require
|
||||
a Docker daemon.
|
||||
Envbuilder transforms the workspace environment itself from a Dev Container spec (i.e `devcontainer.json`),
|
||||
rather than running containers inside the workspace. It does not require a Docker
|
||||
daemon.
|
||||
|
||||
> [!NOTE]
|
||||
> Envbuilder is in **maintenance mode**. No new features are planned to be
|
||||
> implemented. For most use cases, the
|
||||
> [Dev Container CLI](#dev-container-cli) or [CI/CD Pre-built](#cicd-pre-built)
|
||||
> approaches are recommended.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Does not require Docker in workspaces.
|
||||
- Easier caching.
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Very complicated to debug, since Envbuilder replaces the filesystem of the
|
||||
container. You can't access that environment within Coder easily if it fails,
|
||||
and you won't have many debug tools.
|
||||
- Does not support all of the Dev Container configuration options.
|
||||
- Does not support discovery of repos with Dev Containers in them.
|
||||
- Less flexible and more complex in general.
|
||||
|
||||
**Best for:**
|
||||
|
||||
- Environments where Docker is unavailable or restricted
|
||||
- Infrastructure-level control over image builds, caching, and security scanning
|
||||
- Kubernetes-native deployments without privileged containers
|
||||
- Environments where Docker is unavailable or restricted.
|
||||
- Infrastructure-level control over image builds, caching, and security scanning.
|
||||
- Kubernetes-native deployments without privileged containers.
|
||||
|
||||
[Configure Envbuilder](./envbuilder/index.md)
|
||||
See the [Envbuilder](./envbuilder/index.md) page for instructions.
|
||||
|
||||
## CI/CD Pre-built
|
||||
|
||||
Build the Dev Container image from CI/CD and pull it from within Terraform. This
|
||||
approach separates the image build step from the workspace startup, resulting in
|
||||
fast startup times and a generic template that doesn't have any
|
||||
Dev Container-specific configuration items.
|
||||
|
||||
**Pros:**
|
||||
|
||||
- Standard Dev Container implementation via Microsoft's official `@devcontainers/cli` package.
|
||||
- Faster startup time — no need for a specific caching setup.
|
||||
- The template is generic and doesn't have any Dev Container-specific
|
||||
configuration items.
|
||||
- Versioned via image tags.
|
||||
- Testable pipeline.
|
||||
|
||||
**Cons:**
|
||||
|
||||
- Adds a build step.
|
||||
- Does not support all of the runtime options, but still supports more options
|
||||
than Envbuilder.
|
||||
- Does not support discovery of repos with Dev Containers.
|
||||
- Slow feedback loop (build, then test).
|
||||
|
||||
**Best for:**
|
||||
|
||||
- Controlled and centralized releases with less dev flexibility.
|
||||
- Teams that already have CI/CD pipelines for building images.
|
||||
- Environments that need fast, predictable startup times.
|
||||
|
||||
For an example workflow, see the
|
||||
[uwu/basic-env CI/CD workflow](https://github.com/uwu/basic-env/blob/main/.github/workflows/_build-and-push.yml).
|
||||
|
||||
@@ -1,13 +1,14 @@
|
||||
# Configure a template for Dev Containers
|
||||
|
||||
This guide covers the Dev Containers Integration, which uses Docker. For
|
||||
This guide covers the Dev Containers CLI Integration, which uses Docker. For
|
||||
environments without Docker, see [Envbuilder](./envbuilder/index.md) as an
|
||||
alternative.
|
||||
|
||||
To enable Dev Containers in workspaces, configure your template with the Dev Containers
|
||||
modules and configurations outlined in this doc.
|
||||
To enable Dev Containers in workspaces, configure your template with the [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli)
|
||||
module and configurations outlined in this doc.
|
||||
|
||||
Dev Containers are currently not supported in Windows or macOS workspaces.
|
||||
> [!WARNING]
|
||||
> Dev Containers are currently not supported in Windows or macOS workspaces.
|
||||
|
||||
## Configuration Modes
|
||||
|
||||
@@ -16,7 +17,7 @@ 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:
|
||||
Container(s) should be started in your workspace. This approach provides:
|
||||
|
||||
- Predictable behavior and explicit control
|
||||
- Clear template configuration
|
||||
@@ -38,7 +39,7 @@ or work with many projects, as it reduces template maintenance overhead.
|
||||
|
||||
Use the
|
||||
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
|
||||
to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
to ensure that the `@devcontainers/cli` NPM package is installed in your workspace:
|
||||
|
||||
```terraform
|
||||
module "devcontainers-cli" {
|
||||
@@ -54,7 +55,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 specific Dev Container in your workspace, ensuring it's
|
||||
ready when you access the workspace:
|
||||
|
||||
```terraform
|
||||
@@ -74,9 +75,9 @@ 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
|
||||
## Enable Dev Containers CLI Integration
|
||||
|
||||
Dev Containers integration is **enabled by default** in Coder 2.24.0 and later.
|
||||
The Dev Containers CLI 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.
|
||||
|
||||
@@ -110,7 +111,7 @@ the feature.
|
||||
|
||||
**Default: `true`** • **Added in: v2.24.0**
|
||||
|
||||
Enables the Dev Containers integration in the Coder agent.
|
||||
Enables the Dev Containers CLI Integration in the Coder agent.
|
||||
|
||||
The Dev Containers feature is enabled by default. You can explicitly disable it
|
||||
by setting this to `false`.
|
||||
@@ -160,6 +161,8 @@ always auto-start regardless of this setting.
|
||||
> [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).
|
||||
>
|
||||
> If you really need modules, look into [other Dev Container options](./index.md#comparison)
|
||||
|
||||
Developers can customize individual dev containers using the `customizations.coder`
|
||||
block in their `devcontainer.json` file. Available options include:
|
||||
@@ -174,7 +177,7 @@ block in their `devcontainer.json` file. Available options include:
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
## Simplified Template Example
|
||||
|
||||
Here's a simplified template example that uses Dev Containers with manual
|
||||
configuration:
|
||||
@@ -216,7 +219,9 @@ resource "coder_devcontainer" "my-repository" {
|
||||
### Alternative: Project Discovery with Autostart
|
||||
|
||||
By default, discovered containers appear in the dashboard but developers must
|
||||
manually start them. To have them start automatically, enable autostart:
|
||||
manually start them. To have them start automatically, enable autostart by setting the `CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE` environment to `true` within the workspace.
|
||||
|
||||
For example, with a Docker-based template:
|
||||
|
||||
```terraform
|
||||
resource "docker_container" "workspace" {
|
||||
@@ -236,24 +241,24 @@ With autostart enabled:
|
||||
|
||||
- Discovered containers automatically build and start during workspace
|
||||
initialization
|
||||
- The `coder_devcontainer` resource is not required
|
||||
- The [`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/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
|
||||
> When using project discovery, you still need to install the `devcontainer` 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.
|
||||
starter template demonstrates the Dev Containers CLI Integration using Docker-in-Docker.
|
||||
It includes the [`devcontainers-cli`](https://registry.coder.com/modules/coder/devcontainers-cli) module, [`git-clone`](https://registry.coder.com/modules/git-clone) module, and the
|
||||
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer) resource.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)
|
||||
- [Dev Containers CLI Integration user guide](../../../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)
|
||||
|
||||
@@ -4,11 +4,11 @@ Dev containers extend your template with containerized development environments,
|
||||
allowing developers to work in consistent, reproducible setups defined by
|
||||
`devcontainer.json` files.
|
||||
|
||||
Coder's Dev Containers Integration uses the standard `@devcontainers/cli` and
|
||||
Coder's main Dev Containers Integration uses the standard `@devcontainers/cli` and
|
||||
Docker to run containers inside workspaces.
|
||||
|
||||
For setup instructions, see
|
||||
[Dev Containers Integration](../../integrations/devcontainers/integration.md).
|
||||
|
||||
For an alternative approach that doesn't require Docker, see
|
||||
[Envbuilder](../../integrations/devcontainers/envbuilder/index.md).
|
||||
For alternative approaches and comparisons between them, see the
|
||||
[Dev Containers](../../integrations/devcontainers/index.md) page.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# Dev Containers
|
||||
# Dev Containers (via `@devcontainers/cli` CLI)
|
||||
|
||||
[Dev containers](https://containers.dev/) define your development environment
|
||||
as code using a `devcontainer.json` file. Coder's Dev Containers integration
|
||||
@@ -6,28 +6,27 @@ uses the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
|
||||
[Docker](https://www.docker.com) to seamlessly build and run these containers,
|
||||
with management in your dashboard.
|
||||
|
||||
This guide covers the Dev Containers integration. For workspaces without Docker,
|
||||
administrators can configure
|
||||
[Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md) instead,
|
||||
which builds the workspace image itself from your dev container configuration.
|
||||
This guide covers the Dev Containers CLI integration which requires Docker. For workspaces without Docker in them,
|
||||
administrators can look into
|
||||
[other options](../../admin/integrations/devcontainers/index.md#comparison) instead.
|
||||
|
||||
_Dev containers appear as sub-agents with their own apps, SSH access, and port forwarding_
|
||||
_Dev containers appear as sub-agents with their own apps, SSH access, and port forwarding_
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Coder version 2.24.0 or later
|
||||
- Docker available inside your workspace
|
||||
- The `@devcontainers/cli` installed in your workspace
|
||||
- Docker available inside your workspace (via Docker-in-Docker or a mounted socket, see [Docker in workspaces](../../admin/templates/extending-templates/docker-in-workspaces.md) for details on how to achieve this)
|
||||
- The `devcontainer` CLI (`@devcontainers/cli` NPM package) 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/integrations/devcontainers/integration.md)
|
||||
The Dev Containers CLI integration is enabled by default in Coder.
|
||||
|
||||
Most templates with Dev Containers support include all these prerequisites. See
|
||||
[Configure a template for Dev Containers](../../admin/integrations/devcontainers/integration.md)
|
||||
for setup details.
|
||||
|
||||
## Features
|
||||
|
||||
- Automatic dev container detection from repositories
|
||||
- Automatic Dev Container detection from repositories
|
||||
- Seamless container startup during workspace initialization
|
||||
- Change detection with outdated status indicator
|
||||
- On-demand container rebuild via dashboard button
|
||||
@@ -46,7 +45,7 @@ development environment. You can place it in:
|
||||
- `.devcontainer.json` (root of repository)
|
||||
- `.devcontainer/<folder>/devcontainer.json` (for multiple configurations)
|
||||
|
||||
The third option allows monorepos to define multiple dev container
|
||||
The third option allows monorepos to define multiple Dev Container
|
||||
configurations in separate sub-folders. See the
|
||||
[Dev Container specification](https://containers.dev/implementors/spec/#devcontainerjson)
|
||||
for details.
|
||||
@@ -63,52 +62,52 @@ Here's a minimal example:
|
||||
For more configuration options, see the
|
||||
[Dev Container specification](https://containers.dev/).
|
||||
|
||||
### Start your dev container
|
||||
### Start your Dev Container
|
||||
|
||||
Coder automatically discovers dev container configurations in your repositories
|
||||
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.
|
||||
|
||||
_Coder detects dev container configurations and displays them with a Start button_
|
||||
_Coder detects Dev Container configurations and displays them with a Start button_
|
||||
|
||||
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.
|
||||
|
||||
### Connect to your dev container
|
||||
### Connect to your Dev Container
|
||||
|
||||
Once running, your dev container appears as a sub-agent in your workspace
|
||||
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
|
||||
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
|
||||
The Dev Containers CLI 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 dev container configurations.
|
||||
1. Detected dev containers appear in the Coder dashboard.
|
||||
1. The integration detects repositories with Dev Container configurations.
|
||||
1. Detected Dev Containers appear in the Coder dashboard.
|
||||
1. If auto-start is configured (via `coder_devcontainer` or autostart settings),
|
||||
the integration builds and starts the dev container automatically.
|
||||
the integration builds and starts the Dev Container automatically.
|
||||
1. Coder creates a sub-agent for the running container, enabling direct access.
|
||||
|
||||
Without auto-start, users can manually start discovered dev containers from the
|
||||
Without auto-start, users can manually start discovered Dev Containers from the
|
||||
dashboard.
|
||||
|
||||
### Agent naming
|
||||
|
||||
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`
|
||||
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`.
|
||||
|
||||
Agent names are sanitized to contain only lowercase alphanumeric characters and
|
||||
@@ -124,17 +123,17 @@ in your `devcontainer.json`.
|
||||
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
|
||||
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
|
||||
- Some advanced Dev Container features may have limited support
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE
|
||||
- [Working with Dev Containers](./working-with-dev-containers.md) — SSH, IDE
|
||||
integration, and port forwarding
|
||||
- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent
|
||||
- [Customizing Dev Containers](./customizing-dev-containers.md) — Custom agent
|
||||
names, apps, and display options
|
||||
- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) —
|
||||
- [Troubleshooting Dev Containers](./troubleshooting-dev-containers.md) —
|
||||
Diagnose common issues
|
||||
- [Dev Container specification](https://containers.dev/) — Advanced
|
||||
configuration options
|
||||
|
||||
Reference in New Issue
Block a user