mirror of
https://github.com/coder/coder.git
synced 2026-06-02 20:48:20 +00:00
docs: restructure dev container documentation (#21157)
Dev container admin docs were scattered across two locations: the Docker-based
integration under extending-templates/ and Envbuilder under managing-templates/.
There was no landing page explaining that two approaches exist or helping admins
choose between them.
This moves everything under admin/integrations/devcontainers/ with a decision
guide at the top. Dev containers are an integration with the dev container
specification, so integrations/ is a natural fit alongside JFrog, Vault, etc.
Stub pages remain at the original locations for discoverability.
New structure:
admin/integrations/devcontainers/
├── index.md # Landing page + decision guide
├── integration.md # Docker-based dev containers
└── envbuilder/
├── index.md
├── add-envbuilder.md
├── envbuilder-security-caching.md
└── envbuilder-releases-known-issues.md
Refs #21080
This commit is contained in:
Mathias Fredriksson
committed by
GitHub
GitHub
parent
244e6ca027
commit
97bc7eb9e5
+1
-1
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
|
||||
### Development containers (dev containers)
|
||||
|
||||
- A
|
||||
[Development Container](./templates/extending-templates/devcontainers.md)
|
||||
[Development Container](./integrations/devcontainers/index.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
|
||||
|
||||
+2
-2
@@ -2,7 +2,7 @@
|
||||
|
||||
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
|
||||
URL as a [parameter](../../../templates/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.
|
||||
|
||||
@@ -127,7 +127,7 @@ their development environments:
|
||||
| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
|
||||
|
||||
Your template can prompt the user for a repo URL with
|
||||
[parameters](../../extending-templates/parameters.md):
|
||||
[parameters](../../../templates/extending-templates/parameters.md):
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
# Envbuilder
|
||||
|
||||
Envbuilder is an open-source tool that builds development environments from
|
||||
[dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||
Unlike the [Dev Containers integration](../integration.md),
|
||||
Envbuilder transforms the workspace image itself rather than running containers
|
||||
inside the workspace.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> For most use cases, we recommend the
|
||||
> [Dev Containers integration](../integration.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.
|
||||
|
||||
By using dev containers, developers can customize their workspaces with tools
|
||||
pre-approved by platform teams in registries like
|
||||
[JFrog Artifactory](../../jfrog-artifactory.md). This simplifies
|
||||
workflows, reduces the need for tickets and approvals, and promotes greater
|
||||
independence for developers.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
An administrator should construct or choose a base image and create a template
|
||||
that includes a `devcontainer_builder` image before a developer team configures
|
||||
dev containers.
|
||||
|
||||
## Devcontainer Features
|
||||
|
||||
[Dev container Features](https://containers.dev/implementors/features/) allow
|
||||
owners of a project to specify self-contained units of code and runtime
|
||||
configuration that can be composed together on top of an existing base image.
|
||||
This is a good place to install project-specific tools, such as
|
||||
language-specific runtimes and compilers.
|
||||
|
||||
## Coder Envbuilder
|
||||
|
||||
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
|
||||
maintained by Coder that runs dev containers via Coder templates and your
|
||||
underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
|
||||
|
||||
It is independently packaged and versioned from the centralized Coder
|
||||
open-source project. This means that Envbuilder can be used with Coder, but it
|
||||
is not required. It also means that dev container builds can scale independently
|
||||
of the Coder control plane and even run within a CI/CD pipeline.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Add an Envbuilder template](./add-envbuilder.md)
|
||||
@@ -0,0 +1,49 @@
|
||||
# Dev Containers
|
||||
|
||||
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:
|
||||
|
||||
- **Standardize environments**: Eliminate "works on my machine" issues while
|
||||
still allowing developers to customize their tools within approved boundaries.
|
||||
- **Scale efficiently**: Let developers maintain their own environment
|
||||
definitions, reducing the burden on platform teams.
|
||||
- **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.
|
||||
|
||||
## Dev Containers Integration
|
||||
|
||||
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.
|
||||
|
||||
**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
|
||||
|
||||
[Configure Dev Containers Integration](./integration.md)
|
||||
|
||||
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.
|
||||
|
||||
**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
|
||||
|
||||
[Configure Envbuilder](./envbuilder/index.md)
|
||||
@@ -0,0 +1,266 @@
|
||||
# Configure a template for Dev Containers
|
||||
|
||||
> [!NOTE]
|
||||
> 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.
|
||||
|
||||
> [!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
|
||||
|
||||
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
|
||||
|
||||
Use the
|
||||
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
|
||||
to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
|
||||
```terraform
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, install the devcontainer CLI manually in your base image.
|
||||
|
||||
## Configure Automatic Dev Container Startup
|
||||
|
||||
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
|
||||
ready when you access the workspace:
|
||||
|
||||
```terraform
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
agent_id = coder_agent.dev.id
|
||||
workspace_folder = "/home/coder/my-repository"
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The `workspace_folder` attribute must specify the location of the dev
|
||||
> container's workspace and should point to a valid project folder containing a
|
||||
> `devcontainer.json` file.
|
||||
|
||||
<!-- nolint:MD028/no-blanks-blockquote -->
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
|
||||
> 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.
|
||||
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=false", # Explicitly disable
|
||||
# ... Other environment variables.
|
||||
]
|
||||
# ... Other container configuration.
|
||||
}
|
||||
```
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
### 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
|
||||
|
||||
> [!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).
|
||||
|
||||
Developers can customize individual dev containers using the `customizations.coder`
|
||||
block in their `devcontainer.json` file. Available options include:
|
||||
|
||||
- `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
|
||||
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
|
||||
Here's a simplified template example that uses Dev Containers with manual
|
||||
configuration:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
coder = { source = "coder/coder" }
|
||||
docker = { source = "kreuzwerker/docker" }
|
||||
}
|
||||
}
|
||||
|
||||
provider "coder" {}
|
||||
data "coder_workspace" "me" {}
|
||||
data "coder_workspace_owner" "me" {}
|
||||
|
||||
resource "coder_agent" "dev" {
|
||||
arch = "amd64"
|
||||
os = "linux"
|
||||
startup_script_behavior = "blocking"
|
||||
startup_script = "sudo service docker start"
|
||||
shutdown_script = "sudo service docker stop"
|
||||
# ...
|
||||
}
|
||||
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
agent_id = coder_agent.dev.id
|
||||
workspace_folder = "/home/coder/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:
|
||||
|
||||
```terraform
|
||||
resource "docker_container" "workspace" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
image = "codercom/oss-dogfood:latest"
|
||||
env = [
|
||||
# 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 autostart enabled:
|
||||
|
||||
- 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)
|
||||
@@ -1,263 +1,14 @@
|
||||
# Configure a template for Dev Containers
|
||||
# Dev Containers
|
||||
|
||||
To enable Dev Containers in workspaces, configure your template with the Dev Containers
|
||||
modules and configurations outlined in this doc.
|
||||
Dev containers extend your template with containerized development environments,
|
||||
allowing developers to work in consistent, reproducible setups defined by
|
||||
`devcontainer.json` files.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> Dev Containers require a **Linux or macOS workspace**. Windows is not supported.
|
||||
Coder's Dev Containers Integration uses the standard `@devcontainers/cli` and
|
||||
Docker to run containers inside workspaces.
|
||||
|
||||
## Configuration Modes
|
||||
For setup instructions, see
|
||||
[Dev Containers Integration](../../integrations/devcontainers/integration.md).
|
||||
|
||||
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
|
||||
|
||||
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
|
||||
|
||||
Use the
|
||||
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
|
||||
to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
|
||||
```terraform
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
```
|
||||
|
||||
Alternatively, install the devcontainer CLI manually in your base image.
|
||||
|
||||
## Configure Automatic Dev Container Startup
|
||||
|
||||
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
|
||||
ready when you access the workspace:
|
||||
|
||||
```terraform
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
agent_id = coder_agent.dev.id
|
||||
workspace_folder = "/home/coder/my-repository"
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> The `workspace_folder` attribute must specify the location of the dev
|
||||
> container's workspace and should point to a valid project folder containing a
|
||||
> `devcontainer.json` file.
|
||||
|
||||
<!-- nolint:MD028/no-blanks-blockquote -->
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
|
||||
> 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.
|
||||
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=false", # Explicitly disable
|
||||
# ... Other environment variables.
|
||||
]
|
||||
# ... Other container configuration.
|
||||
}
|
||||
```
|
||||
|
||||
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 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.
|
||||
|
||||
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.
|
||||
|
||||
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
### 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
|
||||
|
||||
> [!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).
|
||||
|
||||
Developers can customize individual dev containers using the `customizations.coder`
|
||||
block in their `devcontainer.json` file. Available options include:
|
||||
|
||||
- `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
|
||||
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
|
||||
Here's a simplified template example that uses Dev Containers with manual
|
||||
configuration:
|
||||
|
||||
```terraform
|
||||
terraform {
|
||||
required_providers {
|
||||
coder = { source = "coder/coder" }
|
||||
docker = { source = "kreuzwerker/docker" }
|
||||
}
|
||||
}
|
||||
|
||||
provider "coder" {}
|
||||
data "coder_workspace" "me" {}
|
||||
data "coder_workspace_owner" "me" {}
|
||||
|
||||
resource "coder_agent" "dev" {
|
||||
arch = "amd64"
|
||||
os = "linux"
|
||||
startup_script_behavior = "blocking"
|
||||
startup_script = "sudo service docker start"
|
||||
shutdown_script = "sudo service docker stop"
|
||||
# ...
|
||||
}
|
||||
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
|
||||
resource "coder_devcontainer" "my-repository" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
agent_id = coder_agent.dev.id
|
||||
workspace_folder = "/home/coder/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:
|
||||
|
||||
```terraform
|
||||
resource "docker_container" "workspace" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
image = "codercom/oss-dogfood:latest"
|
||||
env = [
|
||||
# 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 autostart enabled:
|
||||
|
||||
- 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)
|
||||
For an alternative approach that doesn't require Docker, see
|
||||
[Envbuilder](../../integrations/devcontainers/envbuilder/index.md).
|
||||
|
||||
@@ -48,9 +48,9 @@ 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 Containers integration](./extending-templates/devcontainers.md): Enable
|
||||
- [Dev Containers integration](../integrations/devcontainers/integration.md): Enable
|
||||
native dev containers support using `@devcontainers/cli` and Docker.
|
||||
- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
|
||||
- [Envbuilder](../integrations/devcontainers/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
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
# Envbuilder
|
||||
|
||||
Envbuilder shifts environment definition from template administrators to
|
||||
developers. Instead of baking tools into template images, developers define
|
||||
their environments via `devcontainer.json` files in their repositories.
|
||||
|
||||
Envbuilder transforms the workspace image itself from a dev container
|
||||
configuration, without requiring a Docker daemon.
|
||||
|
||||
For setup instructions, see
|
||||
[Envbuilder documentation](../../integrations/devcontainers/envbuilder/index.md).
|
||||
|
||||
For an alternative that uses Docker inside workspaces, see
|
||||
[Dev Containers Integration](../../integrations/devcontainers/integration.md).
|
||||
@@ -1,131 +0,0 @@
|
||||
# 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.
|
||||
|
||||
By using dev containers, developers can customize their workspaces with tools
|
||||
pre-approved by platform teams in registries like
|
||||
[JFrog Artifactory](../../../integrations/jfrog-artifactory.md). This simplifies
|
||||
workflows, reduces the need for tickets and approvals, and promotes greater
|
||||
independence for developers.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
An administrator should construct or choose a base image and create a template
|
||||
that includes a `devcontainer_builder` image before a developer team configures
|
||||
dev containers.
|
||||
|
||||
## Benefits of devcontainers
|
||||
|
||||
There are several benefits to adding a dev container-compatible template to
|
||||
Coder:
|
||||
|
||||
- Reliability through standardization
|
||||
- Scalability for growing teams
|
||||
- Improved security
|
||||
- Performance efficiency
|
||||
- Cost Optimization
|
||||
|
||||
### Reliability through standardization
|
||||
|
||||
Use dev containers to empower development teams to personalize their own
|
||||
environments while maintaining consistency and security through an approved and
|
||||
hardened base image.
|
||||
|
||||
Standardized environments ensure uniform behavior across machines and team
|
||||
members, eliminating "it works on my machine" issues and creating a stable
|
||||
foundation for development and testing. Containerized setups reduce dependency
|
||||
conflicts and misconfigurations, enhancing build stability.
|
||||
|
||||
### Scalability for growing teams
|
||||
|
||||
Dev containers allow organizations to handle multiple projects and teams
|
||||
efficiently.
|
||||
|
||||
You can leverage platforms like Kubernetes to allocate resources on demand,
|
||||
optimizing costs and ensuring fair distribution of quotas. Developer teams can
|
||||
use efficient custom images and independently configure the contents of their
|
||||
version-controlled dev containers.
|
||||
|
||||
This approach allows organizations to scale seamlessly, reducing the maintenance
|
||||
burden on the administrators that support diverse projects while allowing
|
||||
development teams to maintain their own images and onboard new users quickly.
|
||||
|
||||
### Improved security
|
||||
|
||||
Since Coder and Envbuilder run on your own infrastructure, you can use firewalls
|
||||
and cluster-level policies to ensure Envbuilder only downloads packages from
|
||||
your secure registry powered by JFrog Artifactory or Sonatype Nexus.
|
||||
Additionally, Envbuilder can be configured to push the full image back to your
|
||||
registry for additional security scanning.
|
||||
|
||||
This means that Coder admins can require hardened base images and packages,
|
||||
while still allowing developer self-service.
|
||||
|
||||
Envbuilder runs inside a small container image but does not require a Docker
|
||||
daemon in order to build a dev container. This is useful in environments where
|
||||
you may not have access to a Docker socket for security reasons, but still need
|
||||
to work with a container.
|
||||
|
||||
### Performance efficiency
|
||||
|
||||
Create a unique image for each project to reduce the dependency size of any
|
||||
given project.
|
||||
|
||||
Envbuilder has various caching modes to ensure workspaces start as fast as
|
||||
possible, such as layer caching and even full image caching and fetching via the
|
||||
[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs).
|
||||
|
||||
### Cost optimization
|
||||
|
||||
By creating unique images per-project, you remove unnecessary dependencies and
|
||||
reduce the workspace size and resource consumption of any given project. Full
|
||||
image caching ensures optimal start and stop times.
|
||||
|
||||
## When to use a dev container
|
||||
|
||||
Dev containers are a good fit for developer teams who are familiar with Docker
|
||||
and are already using containerized development environments. If you have a
|
||||
large number of projects with different toolchains, dependencies, or that depend
|
||||
on a particular Linux distribution, dev containers make it easier to quickly
|
||||
switch between projects.
|
||||
|
||||
They may also be a great fit for more restricted environments where you may not
|
||||
have access to a Docker daemon since it doesn't need one to work.
|
||||
|
||||
## Devcontainer Features
|
||||
|
||||
[Dev container Features](https://containers.dev/implementors/features/) allow
|
||||
owners of a project to specify self-contained units of code and runtime
|
||||
configuration that can be composed together on top of an existing base image.
|
||||
This is a good place to install project-specific tools, such as
|
||||
language-specific runtimes and compilers.
|
||||
|
||||
## Coder Envbuilder
|
||||
|
||||
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
|
||||
maintained by Coder that runs dev containers via Coder templates and your
|
||||
underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
|
||||
|
||||
It is independently packaged and versioned from the centralized Coder
|
||||
open-source project. This means that Envbuilder can be used with Coder, but it
|
||||
is not required. It also means that dev container builds can scale independently
|
||||
of the Coder control plane and even run within a CI/CD pipeline.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Add an Envbuilder template](./add-envbuilder.md)
|
||||
@@ -70,5 +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.
|
||||
|
||||
- [Configure a template for Dev Containers](../extending-templates/devcontainers.md) (recommended)
|
||||
- [Learn about Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||
- [Configure a template for Dev Containers](../../integrations/devcontainers/integration.md) (recommended)
|
||||
- [Learn about Envbuilder](../../integrations/devcontainers/envbuilder/index.md) (alternative for environments without Docker)
|
||||
|
||||
@@ -96,6 +96,6 @@ coder templates delete <template-name>
|
||||
## Next steps
|
||||
|
||||
- [Image management](./image-management.md)
|
||||
- [Dev Containers integration](../extending-templates/devcontainers.md) (recommended)
|
||||
- [Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||
- [Dev Containers integration](../../integrations/devcontainers/integration.md) (recommended)
|
||||
- [Envbuilder](../../integrations/devcontainers/envbuilder/index.md) (alternative for environments without Docker)
|
||||
- [Change management](./change-management.md)
|
||||
|
||||
+38
-21
@@ -533,25 +533,8 @@
|
||||
},
|
||||
{
|
||||
"title": "Envbuilder",
|
||||
"description": "Build dev containers using Envbuilder for environments without Docker",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/index.md",
|
||||
"children": [
|
||||
{
|
||||
"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": "Envbuilder security and caching",
|
||||
"description": "Configure Envbuilder authentication and caching",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md"
|
||||
},
|
||||
{
|
||||
"title": "Envbuilder releases and known issues",
|
||||
"description": "Envbuilder releases and known issues",
|
||||
"path": "./admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md"
|
||||
}
|
||||
]
|
||||
"description": "Shift environment definition to repositories",
|
||||
"path": "./admin/templates/managing-templates/envbuilder.md"
|
||||
},
|
||||
{
|
||||
"title": "Template Dependencies",
|
||||
@@ -663,8 +646,8 @@
|
||||
"path": "./admin/templates/extending-templates/provider-authentication.md"
|
||||
},
|
||||
{
|
||||
"title": "Configure a template for dev containers",
|
||||
"description": "How to use configure your template for dev containers",
|
||||
"title": "Dev Containers",
|
||||
"description": "Extend templates with containerized dev environments",
|
||||
"path": "./admin/templates/extending-templates/devcontainers.md"
|
||||
},
|
||||
{
|
||||
@@ -764,6 +747,40 @@
|
||||
"title": "OAuth2 Provider",
|
||||
"description": "Use Coder as an OAuth2 provider",
|
||||
"path": "./admin/integrations/oauth2-provider.md"
|
||||
},
|
||||
{
|
||||
"title": "Dev Containers",
|
||||
"description": "Configure dev container support using Docker or Envbuilder",
|
||||
"path": "./admin/integrations/devcontainers/index.md",
|
||||
"children": [
|
||||
{
|
||||
"title": "Dev Containers Integration",
|
||||
"description": "Configure native dev containers with Docker",
|
||||
"path": "./admin/integrations/devcontainers/integration.md"
|
||||
},
|
||||
{
|
||||
"title": "Envbuilder",
|
||||
"description": "Build dev containers without Docker",
|
||||
"path": "./admin/integrations/devcontainers/envbuilder/index.md",
|
||||
"children": [
|
||||
{
|
||||
"title": "Add an Envbuilder template",
|
||||
"description": "How to add an Envbuilder template",
|
||||
"path": "./admin/integrations/devcontainers/envbuilder/add-envbuilder.md"
|
||||
},
|
||||
{
|
||||
"title": "Security and caching",
|
||||
"description": "Configure authentication and caching",
|
||||
"path": "./admin/integrations/devcontainers/envbuilder/envbuilder-security-caching.md"
|
||||
},
|
||||
{
|
||||
"title": "Releases and known issues",
|
||||
"description": "Release channels and known issues",
|
||||
"path": "./admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
||||
@@ -54,7 +54,7 @@ and shown in the UI, but users must manually start it.
|
||||
> [!NOTE]
|
||||
>
|
||||
> The `autoStart` option only takes effect when your template administrator has
|
||||
> enabled [`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`](../../admin/templates/extending-templates/devcontainers.md#coder_agent_devcontainers_discovery_autostart_enable).
|
||||
> enabled [`CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE`](../../admin/integrations/devcontainers/integration.md#coder_agent_devcontainers_discovery_autostart_enable).
|
||||
> If this setting is disabled at the template level, containers won't auto-start
|
||||
> regardless of this option.
|
||||
|
||||
|
||||
@@ -6,6 +6,12 @@ containers in Coder workspaces. This feature leverages the
|
||||
[Docker](https://www.docker.com) to provide a streamlined development
|
||||
experience.
|
||||
|
||||
> [!NOTE]
|
||||
> This guide covers the Dev Containers Integration, which uses Docker.
|
||||
> For environments without Docker, administrators can configure
|
||||
> [Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md)
|
||||
> as an alternative.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Coder version 2.24.0 or later
|
||||
@@ -15,7 +21,7 @@ experience.
|
||||
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)
|
||||
[Configure a template for dev containers](../../admin/integrations/devcontainers/integration.md)
|
||||
for setup details.
|
||||
|
||||
## Features
|
||||
@@ -119,10 +125,6 @@ in your `devcontainer.json`.
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user