mirror of
https://github.com/coder/coder.git
synced 2026-09-24 15:04:27 +08:00
docs: rewrite dev containers documentation for GA (#21080)
docs: rewrite dev containers documentation for GA Corrects inaccuracies in SSH examples (deprecated `--container` flag), port forwarding (native sub-agent forwarding is primary), and prerequisites (dev containers are on by default). Fixes template descriptions: docker-devcontainer uses native Dev Containers while AWS/Kubernetes templates use Envbuilder. Renames admin docs folder from `devcontainers/` to `envbuilder/` to reflect actual content. Adds customization guide documenting agent naming, display apps, custom apps, and variable interpolation. Documents multi-repo workspace support and adds note about Terraform module limitations with sub-agents. Fixes module registry URLs. Refs #18907
This commit is contained in:
Mathias Fredriksson
+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/managing-templates/devcontainers/index.md)
|
||||
[Development Container](./templates/extending-templates/devcontainers.md)
|
||||
is an open-source specification for defining development environments (called
|
||||
dev containers). It is generally stored in VCS alongside associated source
|
||||
code. It can reference an existing base image, or a custom Dockerfile that
|
||||
|
||||
@@ -25,7 +25,9 @@ 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.
|
||||
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
|
||||
|
||||
@@ -36,7 +38,7 @@ to ensure the `@devcontainers/cli` is installed in your workspace:
|
||||
```terraform
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
```
|
||||
@@ -72,6 +74,10 @@ resource "coder_devcontainer" "my-repository" {
|
||||
> 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.
|
||||
@@ -119,15 +125,17 @@ by setting this to `false`.
|
||||
|
||||
Enables automatic discovery of Dev Containers in Git repositories.
|
||||
|
||||
When enabled, the agent will:
|
||||
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.
|
||||
|
||||
- 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
|
||||
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.
|
||||
|
||||
You can disable automatic discovery by setting this to `false` if you prefer to
|
||||
use only the `coder_devcontainer` resource for explicit configuration.
|
||||
Set to `false` if you prefer explicit configuration via `coder_devcontainer`.
|
||||
|
||||
### CODER_AGENT_DEVCONTAINERS_DISCOVERY_AUTOSTART_ENABLE
|
||||
|
||||
@@ -142,67 +150,33 @@ 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.
|
||||
> [!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).
|
||||
|
||||
### Ignore Specific Containers
|
||||
Developers can customize individual dev containers using the `customizations.coder`
|
||||
block in their `devcontainer.json` file. Available options include:
|
||||
|
||||
Use the `ignore` option to hide a Dev Container from Coder completely:
|
||||
- `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
|
||||
|
||||
```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
|
||||
For the full reference, see
|
||||
[Customizing dev containers](../../../user-guides/devcontainers/customizing-dev-containers.md).
|
||||
|
||||
## Complete Template Example
|
||||
|
||||
@@ -232,7 +206,7 @@ resource "coder_agent" "dev" {
|
||||
|
||||
module "devcontainers-cli" {
|
||||
count = data.coder_workspace.me.start_count
|
||||
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
|
||||
source = "registry.coder.com/coder/devcontainers-cli/coder"
|
||||
agent_id = coder_agent.dev.id
|
||||
}
|
||||
|
||||
@@ -243,9 +217,10 @@ resource "coder_devcontainer" "my-repository" {
|
||||
}
|
||||
```
|
||||
|
||||
### Alternative: Project Discovery Mode
|
||||
### Alternative: Project Discovery with Autostart
|
||||
|
||||
You can enable automatic starting of discovered Dev Containers:
|
||||
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" {
|
||||
@@ -261,11 +236,11 @@ resource "docker_container" "workspace" {
|
||||
}
|
||||
```
|
||||
|
||||
With this configuration:
|
||||
With autostart enabled:
|
||||
|
||||
- Project discovery is enabled (default behavior)
|
||||
- Discovered containers are automatically started (via the env var)
|
||||
- The `coder_devcontainer` resource is **not** required
|
||||
- Discovered containers automatically build and start during workspace
|
||||
initialization
|
||||
- The `coder_devcontainer` resource is not required
|
||||
- Developers can work with multiple projects seamlessly
|
||||
|
||||
> [!NOTE]
|
||||
@@ -273,8 +248,16 @@ With this configuration:
|
||||
> 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)
|
||||
|
||||
@@ -48,11 +48,10 @@ needs of different teams.
|
||||
|
||||
- [Image management](./managing-templates/image-management.md): Learn how to
|
||||
create and publish images for use within Coder workspaces & templates.
|
||||
- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
|
||||
dev containers to allow teams to bring their own tools into Coder workspaces.
|
||||
- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our
|
||||
new direct devcontainers integration (distinct from Envbuilder-based
|
||||
approach).
|
||||
- [Dev Containers integration](./extending-templates/devcontainers.md): Enable
|
||||
native dev containers support using `@devcontainers/cli` and Docker.
|
||||
- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
|
||||
for environments without Docker access.
|
||||
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
|
||||
Configure your template to prevent certain resources from being destroyed
|
||||
(e.g. user disks).
|
||||
|
||||
+6
-7
@@ -1,10 +1,9 @@
|
||||
# Add a dev container template to Coder
|
||||
# Add an Envbuilder template
|
||||
|
||||
A Coder administrator adds a dev container-compatible template to Coder
|
||||
(Envbuilder). This allows the template to prompt for the developer for their dev
|
||||
container repository's URL as a
|
||||
[parameter](../../extending-templates/parameters.md) when they create their
|
||||
workspace. Envbuilder clones the repo and builds a container from the
|
||||
A Coder administrator adds an Envbuilder-compatible template to Coder. This
|
||||
allows the template to prompt the developer for their dev container repository's
|
||||
URL as a [parameter](../../extending-templates/parameters.md) when they create
|
||||
their workspace. Envbuilder clones the repo and builds a container from the
|
||||
`devcontainer.json` specified in the repo.
|
||||
|
||||
You can create template files through the Coder dashboard, CLI, or you can
|
||||
@@ -143,4 +142,4 @@ Lifecycle scripts are managed by project developers.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Dev container security and caching](./devcontainer-security-caching.md)
|
||||
- [Envbuilder security and caching](./envbuilder-security-caching.md)
|
||||
+1
-1
@@ -1,4 +1,4 @@
|
||||
# Dev container releases and known issues
|
||||
# Envbuilder releases and known issues
|
||||
|
||||
## Release channels
|
||||
|
||||
+3
-3
@@ -1,4 +1,4 @@
|
||||
# Dev container security and caching
|
||||
# Envbuilder security and caching
|
||||
|
||||
Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
|
||||
it with your existing HTTP proxies, firewalls, and artifact managers.
|
||||
@@ -26,7 +26,7 @@ of caching:
|
||||
|
||||
- Caches the entire image, skipping the build process completely (except for
|
||||
post-build
|
||||
[lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
|
||||
[lifecycle scripts](./add-envbuilder.md#dev-container-lifecycle-scripts)).
|
||||
|
||||
Note that caching requires push access to a registry, and may require approval
|
||||
from relevant infrastructure team(s).
|
||||
@@ -62,5 +62,5 @@ You may also wish to consult a
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Dev container releases and known issues](./devcontainer-releases-known-issues.md)
|
||||
- [Envbuilder releases and known issues](./envbuilder-releases-known-issues.md)
|
||||
- [Dotfiles](../../../../user-guides/workspace-dotfiles.md)
|
||||
+15
-6
@@ -1,9 +1,18 @@
|
||||
# Dev containers
|
||||
# Envbuilder
|
||||
|
||||
A Development Container is an
|
||||
[open-source specification](https://containers.dev/implementors/spec/) for
|
||||
defining containerized development environments which are also called
|
||||
development containers (dev containers).
|
||||
Envbuilder is an open-source tool that builds development environments from
|
||||
[dev container](https://containers.dev/implementors/spec/) configuration files.
|
||||
Unlike the [native Dev Containers integration](../../extending-templates/devcontainers.md),
|
||||
Envbuilder transforms the workspace image itself rather than running containers
|
||||
inside the workspace.
|
||||
|
||||
> [!NOTE]
|
||||
>
|
||||
> For most use cases, we recommend the
|
||||
> [native Dev Containers integration](../../extending-templates/devcontainers.md),
|
||||
> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
|
||||
> alternative for environments where Docker is not available or for
|
||||
> administrator-controlled dev container workflows.
|
||||
|
||||
Dev containers provide developers with increased autonomy and control over their
|
||||
Coder cloud development environments.
|
||||
@@ -119,4 +128,4 @@ of the Coder control plane and even run within a CI/CD pipeline.
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Add a dev container template](./add-devcontainer.md)
|
||||
- [Add an Envbuilder template](./add-envbuilder.md)
|
||||
@@ -70,4 +70,5 @@ specific tooling for their projects. The [Dev Container](https://containers.dev)
|
||||
specification allows developers to define their projects dependencies within a
|
||||
`devcontainer.json` in their Git repository.
|
||||
|
||||
- [Learn how to integrate Dev Containers with Coder](./devcontainers/index.md)
|
||||
- [Configure a template for Dev Containers](../extending-templates/devcontainers.md) (recommended)
|
||||
- [Learn about Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||
|
||||
@@ -96,5 +96,6 @@ coder templates delete <template-name>
|
||||
## Next steps
|
||||
|
||||
- [Image management](./image-management.md)
|
||||
- [Devcontainer templates](./devcontainers/index.md)
|
||||
- [Dev Containers integration](../extending-templates/devcontainers.md) (recommended)
|
||||
- [Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
|
||||
- [Change management](./change-management.md)
|
||||
|
||||
Reference in New Issue
Block a user