From 9fae08a82e01366a7fa77b8810b2c43fb66f61d9 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Mon, 8 Dec 2025 10:34:23 +0000 Subject: [PATCH 1/2] docs: restructure dev container documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- docs/_redirects | 12 +- docs/admin/index.md | 2 +- .../envbuilder/add-envbuilder.md | 4 +- .../envbuilder-releases-known-issues.md | 0 .../envbuilder/envbuilder-security-caching.md | 0 .../devcontainers/envbuilder/index.md | 53 ++++ .../admin/integrations/devcontainers/index.md | 49 ++++ .../integrations/devcontainers/integration.md | 266 +++++++++++++++++ .../extending-templates/devcontainers.md | 269 +----------------- docs/admin/templates/index.md | 4 +- .../managing-templates/envbuilder.md | 14 + .../managing-templates/envbuilder/index.md | 131 --------- .../managing-templates/image-management.md | 4 +- .../templates/managing-templates/index.md | 4 +- docs/manifest.json | 59 ++-- .../customizing-dev-containers.md | 2 +- docs/user-guides/devcontainers/index.md | 12 +- 17 files changed, 453 insertions(+), 432 deletions(-) rename docs/admin/{templates/managing-templates => integrations/devcontainers}/envbuilder/add-envbuilder.md (97%) rename docs/admin/{templates/managing-templates => integrations/devcontainers}/envbuilder/envbuilder-releases-known-issues.md (100%) rename docs/admin/{templates/managing-templates => integrations/devcontainers}/envbuilder/envbuilder-security-caching.md (100%) create mode 100644 docs/admin/integrations/devcontainers/envbuilder/index.md create mode 100644 docs/admin/integrations/devcontainers/index.md create mode 100644 docs/admin/integrations/devcontainers/integration.md create mode 100644 docs/admin/templates/managing-templates/envbuilder.md delete mode 100644 docs/admin/templates/managing-templates/envbuilder/index.md diff --git a/docs/_redirects b/docs/_redirects index a97d5edfd918e..7962bbde9a9ad 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -5,9 +5,9 @@ /install/offline#offline-docs /install/airgap#airgap-docs 301 /install/offline#offline-container-images /install/airgap#airgap-container-images 301 -# Redirect old devcontainers folder to envbuilder -/admin/templates/managing-templates/devcontainers /admin/templates/managing-templates/envbuilder 301 -/admin/templates/managing-templates/devcontainers/index /admin/templates/managing-templates/envbuilder 301 -/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/templates/managing-templates/envbuilder/add-envbuilder 301 -/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/templates/managing-templates/envbuilder/envbuilder-security-caching 301 -/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues 301 +# Redirect old devcontainers paths to new integrations location +/admin/templates/managing-templates/devcontainers /admin/integrations/devcontainers/envbuilder 301 +/admin/templates/managing-templates/devcontainers/index /admin/integrations/devcontainers/envbuilder 301 +/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/integrations/devcontainers/envbuilder/add-envbuilder 301 +/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/integrations/devcontainers/envbuilder/envbuilder-security-caching 301 +/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues 301 diff --git a/docs/admin/index.md b/docs/admin/index.md index ff4582d5e2f3d..2bb7f0ebd3b93 100644 --- a/docs/admin/index.md +++ b/docs/admin/index.md @@ -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 diff --git a/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md similarity index 97% rename from docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md rename to docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md index b145ca0963f16..fb065d0958eae 100644 --- a/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md +++ b/docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md @@ -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): ![Dev container parameter screen](../../../../images/templates/devcontainers.png) diff --git a/docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md b/docs/admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues.md similarity index 100% rename from docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md rename to docs/admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues.md diff --git a/docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md b/docs/admin/integrations/devcontainers/envbuilder/envbuilder-security-caching.md similarity index 100% rename from docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md rename to docs/admin/integrations/devcontainers/envbuilder/envbuilder-security-caching.md diff --git a/docs/admin/integrations/devcontainers/envbuilder/index.md b/docs/admin/integrations/devcontainers/envbuilder/index.md new file mode 100644 index 0000000000000..74b9b47d985b7 --- /dev/null +++ b/docs/admin/integrations/devcontainers/envbuilder/index.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) diff --git a/docs/admin/integrations/devcontainers/index.md b/docs/admin/integrations/devcontainers/index.md new file mode 100644 index 0000000000000..4ffbca2145bb9 --- /dev/null +++ b/docs/admin/integrations/devcontainers/index.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) diff --git a/docs/admin/integrations/devcontainers/integration.md b/docs/admin/integrations/devcontainers/integration.md new file mode 100644 index 0000000000000..a77cc6d1f951d --- /dev/null +++ b/docs/admin/integrations/devcontainers/integration.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. + + + +> [!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) diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md index fc0470de99ed4..3e775d0eca0b6 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.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. - - - -> [!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). diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index 8b0af04ba3cc1..138bfdbb98dce 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/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 diff --git a/docs/admin/templates/managing-templates/envbuilder.md b/docs/admin/templates/managing-templates/envbuilder.md new file mode 100644 index 0000000000000..5de7ee658e37b --- /dev/null +++ b/docs/admin/templates/managing-templates/envbuilder.md @@ -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). diff --git a/docs/admin/templates/managing-templates/envbuilder/index.md b/docs/admin/templates/managing-templates/envbuilder/index.md deleted file mode 100644 index d0fe87f5408bf..0000000000000 --- a/docs/admin/templates/managing-templates/envbuilder/index.md +++ /dev/null @@ -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) diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md index e348a72817b15..3794db4f11a38 100644 --- a/docs/admin/templates/managing-templates/image-management.md +++ b/docs/admin/templates/managing-templates/image-management.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) diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md index 5f4efa6c38e18..5b90b8b7bc57a 100644 --- a/docs/admin/templates/managing-templates/index.md +++ b/docs/admin/templates/managing-templates/index.md @@ -96,6 +96,6 @@ coder templates delete ## 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) diff --git a/docs/manifest.json b/docs/manifest.json index fe8620b275136..0d75666899af6 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -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" + } + ] + } + ] } ] }, diff --git a/docs/user-guides/devcontainers/customizing-dev-containers.md b/docs/user-guides/devcontainers/customizing-dev-containers.md index 4a4c614826835..47c38c57feb64 100644 --- a/docs/user-guides/devcontainers/customizing-dev-containers.md +++ b/docs/user-guides/devcontainers/customizing-dev-containers.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. diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md index e54ac20d049e8..42106757b844b 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -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 From ca4e5051406ca96a9bf21782a662ad72ee178c14 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 9 Dec 2025 10:09:28 +0000 Subject: [PATCH 2/2] docs: undo _redirects changes, this file will be removed --- docs/_redirects | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/_redirects b/docs/_redirects index 7962bbde9a9ad..a97d5edfd918e 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -5,9 +5,9 @@ /install/offline#offline-docs /install/airgap#airgap-docs 301 /install/offline#offline-container-images /install/airgap#airgap-container-images 301 -# Redirect old devcontainers paths to new integrations location -/admin/templates/managing-templates/devcontainers /admin/integrations/devcontainers/envbuilder 301 -/admin/templates/managing-templates/devcontainers/index /admin/integrations/devcontainers/envbuilder 301 -/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/integrations/devcontainers/envbuilder/add-envbuilder 301 -/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/integrations/devcontainers/envbuilder/envbuilder-security-caching 301 -/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues 301 +# Redirect old devcontainers folder to envbuilder +/admin/templates/managing-templates/devcontainers /admin/templates/managing-templates/envbuilder 301 +/admin/templates/managing-templates/devcontainers/index /admin/templates/managing-templates/envbuilder 301 +/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/templates/managing-templates/envbuilder/add-envbuilder 301 +/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/templates/managing-templates/envbuilder/envbuilder-security-caching 301 +/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues 301