From 61beb7bfa8b371ef7c1c9399043e3c4a3e1dd6f2 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Fri, 5 Dec 2025 19:42:16 +0200 Subject: [PATCH] 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 --- .markdownlint-cli2.jsonc | 3 + docs/_redirects | 7 + docs/about/contributing/templates.md | 6 +- docs/admin/index.md | 2 +- .../extending-templates/devcontainers.md | 131 ++++---- docs/admin/templates/index.md | 9 +- .../add-envbuilder.md} | 13 +- .../envbuilder-releases-known-issues.md} | 2 +- .../envbuilder-security-caching.md} | 6 +- .../{devcontainers => envbuilder}/index.md | 21 +- .../managing-templates/image-management.md | 3 +- .../templates/managing-templates/index.md | 3 +- docs/manifest.json | 29 +- .../customizing-dev-containers.md | 309 ++++++++++++++++++ docs/user-guides/devcontainers/index.md | 184 +++++++---- .../troubleshooting-dev-containers.md | 107 +++++- .../working-with-dev-containers.md | 162 ++++++--- docs/user-guides/index.md | 4 +- 18 files changed, 763 insertions(+), 238 deletions(-) create mode 100644 .markdownlint-cli2.jsonc rename docs/admin/templates/managing-templates/{devcontainers/add-devcontainer.md => envbuilder/add-envbuilder.md} (92%) rename docs/admin/templates/managing-templates/{devcontainers/devcontainer-releases-known-issues.md => envbuilder/envbuilder-releases-known-issues.md} (95%) rename docs/admin/templates/managing-templates/{devcontainers/devcontainer-security-caching.md => envbuilder/envbuilder-security-caching.md} (92%) rename docs/admin/templates/managing-templates/{devcontainers => envbuilder}/index.md (86%) create mode 100644 docs/user-guides/devcontainers/customizing-dev-containers.md diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc new file mode 100644 index 0000000000..0ce43e7cf9 --- /dev/null +++ b/.markdownlint-cli2.jsonc @@ -0,0 +1,3 @@ +{ + "ignores": ["PLAN.md"], +} diff --git a/docs/_redirects b/docs/_redirects index fdfc401f09..a97d5edfd9 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -4,3 +4,10 @@ # Redirect old offline anchor fragments to new airgap anchors /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 diff --git a/docs/about/contributing/templates.md b/docs/about/contributing/templates.md index 321377bb0f..8240026f87 100644 --- a/docs/about/contributing/templates.md +++ b/docs/about/contributing/templates.md @@ -510,9 +510,9 @@ resource "kubernetes_pod" "workspace" { ## Get help - **Examples**: Review real-world examples from the [official Coder templates](https://registry.coder.com/contributors/coder?tab=templates): - - [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with devcontainer support - - [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Envbuilder containers with dev container support - - [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Envbuilder pods on Kubernetes + - [AWS EC2 (Devcontainer)](https://registry.coder.com/templates/aws-devcontainer) - AWS EC2 VMs with Envbuilder + - [Docker (Devcontainer)](https://registry.coder.com/templates/docker-devcontainer) - Docker-in-Docker with Dev Containers integration + - [Kubernetes (Devcontainer)](https://registry.coder.com/templates/kubernetes-devcontainer) - Kubernetes pods with Envbuilder - [Docker Containers](https://registry.coder.com/templates/docker) - Basic Docker container workspaces - [AWS EC2 (Linux)](https://registry.coder.com/templates/aws-linux) - AWS EC2 VMs for Linux development - [Google Compute Engine (Linux)](https://registry.coder.com/templates/gcp-vm-container) - GCP VM instances diff --git a/docs/admin/index.md b/docs/admin/index.md index 8e527ba420..ff4582d5e2 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/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 diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md index f3eb4835c5..fc0470de99 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -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) diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index e5b0314120..8b0af04ba3 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.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). diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md similarity index 92% rename from docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md rename to docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md index 5d2ac0a07f..b145ca0963 100644 --- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md +++ b/docs/admin/templates/managing-templates/envbuilder/add-envbuilder.md @@ -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) diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md b/docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md similarity index 95% rename from docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md rename to docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md index b8ba3bfddd..721d75bab9 100644 --- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md +++ b/docs/admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues.md @@ -1,4 +1,4 @@ -# Dev container releases and known issues +# Envbuilder releases and known issues ## Release channels diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md similarity index 92% rename from docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md rename to docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md index a0ae51624f..fa61bf360d 100644 --- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md +++ b/docs/admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md @@ -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) diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/envbuilder/index.md similarity index 86% rename from docs/admin/templates/managing-templates/devcontainers/index.md rename to docs/admin/templates/managing-templates/envbuilder/index.md index a4ec140765..d0fe87f540 100644 --- a/docs/admin/templates/managing-templates/devcontainers/index.md +++ b/docs/admin/templates/managing-templates/envbuilder/index.md @@ -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) diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md index 82c552ef67..e348a72817 100644 --- a/docs/admin/templates/managing-templates/image-management.md +++ b/docs/admin/templates/managing-templates/image-management.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) diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md index 9836c7894c..5f4efa6c38 100644 --- a/docs/admin/templates/managing-templates/index.md +++ b/docs/admin/templates/managing-templates/index.md @@ -96,5 +96,6 @@ coder templates delete ## 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) diff --git a/docs/manifest.json b/docs/manifest.json index 2430308162..f49f20f6f9 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -331,6 +331,11 @@ "description": "Access dev containers via SSH, your IDE, or web terminal.", "path": "./user-guides/devcontainers/working-with-dev-containers.md" }, + { + "title": "Customizing dev containers", + "description": "Configure custom agent names, apps, and display options in devcontainer.json.", + "path": "./user-guides/devcontainers/customizing-dev-containers.md" + }, { "title": "Troubleshooting dev containers", "description": "Diagnose and resolve common issues with dev containers in your Coder workspace.", @@ -527,24 +532,24 @@ "path": "./admin/templates/managing-templates/change-management.md" }, { - "title": "Dev containers", - "description": "Learn about using development containers in templates", - "path": "./admin/templates/managing-templates/devcontainers/index.md", + "title": "Envbuilder", + "description": "Build dev containers using Envbuilder for environments without Docker", + "path": "./admin/templates/managing-templates/envbuilder/index.md", "children": [ { - "title": "Add a dev container template", - "description": "How to add a dev container template to Coder", - "path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md" + "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": "Dev container security and caching", - "description": "Configure dev container authentication and caching", - "path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md" + "title": "Envbuilder security and caching", + "description": "Configure Envbuilder authentication and caching", + "path": "./admin/templates/managing-templates/envbuilder/envbuilder-security-caching.md" }, { - "title": "Dev container releases and known issues", - "description": "Dev container releases and known issues", - "path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md" + "title": "Envbuilder releases and known issues", + "description": "Envbuilder releases and known issues", + "path": "./admin/templates/managing-templates/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 new file mode 100644 index 0000000000..4a4c614826 --- /dev/null +++ b/docs/user-guides/devcontainers/customizing-dev-containers.md @@ -0,0 +1,309 @@ +# Customizing dev containers + +Coder supports custom configuration in your `devcontainer.json` file through the +`customizations.coder` block. These options let you control how Coder interacts +with your dev container without requiring template changes. + +## Ignore a dev container + +Use the `ignore` option to hide a dev container from Coder completely: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "customizations": { + "coder": { + "ignore": true + } + } +} +``` + +When `ignore` is set to `true`: + +- The dev container won't appear in the Coder UI +- Coder won't manage or monitor the container + +This is useful for dev containers in your repository that you don't want Coder +to manage. + +## Auto-start + +Control whether your dev container should auto-start using the `autoStart` +option: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "customizations": { + "coder": { + "autoStart": true + } + } +} +``` + +When `autoStart` is set to `true`, the dev container automatically builds and +starts during workspace initialization. + +When `autoStart` is set to `false` or omitted, the dev container is discovered +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). +> If this setting is disabled at the template level, containers won't auto-start +> regardless of this option. + +## Custom agent name + +Each dev container gets an agent name derived from the workspace folder path by +default. You can set a custom name using the `name` option: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "customizations": { + "coder": { + "name": "my-custom-agent" + } + } +} +``` + +The name must contain only lowercase letters, numbers, and hyphens. This name +appears in `coder ssh` commands and the dashboard (e.g., +`coder ssh my-workspace.my-custom-agent`). + +## Display apps + +Control which built-in Coder apps appear for your dev container using +`displayApps`: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "customizations": { + "coder": { + "displayApps": { + "web_terminal": true, + "ssh_helper": true, + "port_forwarding_helper": true, + "vscode": true, + "vscode_insiders": false + } + } + } +} +``` + +Available display apps: + +| App | Description | Default | +|--------------------------|------------------------------|---------| +| `web_terminal` | Web-based terminal access | `true` | +| `ssh_helper` | SSH connection helper | `true` | +| `port_forwarding_helper` | Port forwarding interface | `true` | +| `vscode` | VS Code Desktop integration | `true` | +| `vscode_insiders` | VS Code Insiders integration | `false` | + +## Custom apps + +Define custom applications for your dev container using the `apps` array: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu", + "customizations": { + "coder": { + "apps": [ + { + "slug": "zed", + "displayName": "Zed Editor", + "url": "zed://ssh/${localEnv:CODER_WORKSPACE_AGENT_NAME}.${localEnv:CODER_WORKSPACE_NAME}.${localEnv:CODER_WORKSPACE_OWNER_NAME}.coder${containerWorkspaceFolder}", + "external": true, + "icon": "/icon/zed.svg", + "order": 1 + } + ] + } + } +} +``` + +This example adds a Zed Editor button that opens the dev container directly in +the Zed desktop app via its SSH remote feature. + +Each app supports the following properties: + +| Property | Type | Description | +|---------------|---------|---------------------------------------------------------------| +| `slug` | string | Unique identifier for the app (required) | +| `displayName` | string | Human-readable name shown in the UI | +| `url` | string | URL to open (supports variable interpolation) | +| `command` | string | Command to run instead of opening a URL | +| `icon` | string | Path to an icon (e.g., `/icon/code.svg`) | +| `openIn` | string | `"tab"` or `"slim-window"` (default: `"slim-window"`) | +| `share` | string | `"owner"`, `"authenticated"`, `"organization"`, or `"public"` | +| `external` | boolean | Open as external URL (e.g., for desktop apps) | +| `group` | string | Group name for organizing apps in the UI | +| `order` | number | Sort order for display | +| `hidden` | boolean | Hide the app from the UI | +| `subdomain` | boolean | Use subdomain-based access | +| `healthCheck` | object | Health check configuration (see below) | + +### Health checks + +Configure health checks to monitor app availability: + +```json +{ + "customizations": { + "coder": { + "apps": [ + { + "slug": "web-server", + "displayName": "Web Server", + "url": "http://localhost:8080", + "healthCheck": { + "url": "http://localhost:8080/healthz", + "interval": 5, + "threshold": 2 + } + } + ] + } + } +} +``` + +Health check properties: + +| Property | Type | Description | +|-------------|--------|-------------------------------------------------| +| `url` | string | URL to check for health status | +| `interval` | number | Seconds between health checks | +| `threshold` | number | Number of failures before marking app unhealthy | + +## Variable interpolation + +App URLs and other string values support variable interpolation for dynamic +configuration. + +### Environment variables + +Use `${localEnv:VAR_NAME}` to reference environment variables, with optional +default values: + +```json +{ + "customizations": { + "coder": { + "apps": [ + { + "slug": "my-app", + "url": "http://${localEnv:HOST:127.0.0.1}:${localEnv:PORT:8080}" + } + ] + } + } +} +``` + +### Coder-provided variables + +Coder provides these environment variables automatically: + +| Variable | Description | +|-------------------------------------|------------------------------------| +| `CODER_WORKSPACE_NAME` | Name of the workspace | +| `CODER_WORKSPACE_OWNER_NAME` | Username of the workspace owner | +| `CODER_WORKSPACE_AGENT_NAME` | Name of the dev container agent | +| `CODER_WORKSPACE_PARENT_AGENT_NAME` | Name of the parent workspace agent | +| `CODER_URL` | URL of the Coder deployment | +| `CONTAINER_ID` | Docker container ID | + +### Dev container variables + +Standard dev container variables are also available: + +| Variable | Description | +|-------------------------------|--------------------------------------------| +| `${containerWorkspaceFolder}` | Workspace folder path inside the container | +| `${localWorkspaceFolder}` | Workspace folder path on the host | + +### Session token + +Use `$SESSION_TOKEN` in external app URLs to include the user's session token: + +```json +{ + "customizations": { + "coder": { + "apps": [ + { + "slug": "custom-ide", + "displayName": "Custom IDE", + "url": "custom-ide://open?token=$SESSION_TOKEN&folder=${containerWorkspaceFolder}", + "external": true + } + ] + } + } +} +``` + +## Feature options as environment variables + +When your dev container uses features, Coder exposes feature options as +environment variables. The format is `FEATURE__OPTION_`. + +For example, with this feature configuration: + +```json +{ + "features": { + "ghcr.io/coder/devcontainer-features/code-server:1": { + "port": 9090 + } + } +} +``` + +Coder creates `FEATURE_CODE_SERVER_OPTION_PORT=9090`, which you can reference in +your apps: + +```json +{ + "features": { + "ghcr.io/coder/devcontainer-features/code-server:1": { + "port": 9090 + } + }, + "customizations": { + "coder": { + "apps": [ + { + "slug": "code-server", + "displayName": "Code Server", + "url": "http://localhost:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}", + "icon": "/icon/code.svg" + } + ] + } + } +} +``` + +## Next steps + +- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE + integration, and port forwarding +- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) — + Diagnose common issues diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md index 04ec15c54b..e54ac20d04 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -1,87 +1,137 @@ # Dev Containers Integration -The Dev Containers integration enables seamless creation and management of Dev -Containers in Coder workspaces. This feature leverages the +The Dev Containers integration enables seamless creation and management of dev +containers in Coder workspaces. This feature leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and [Docker](https://www.docker.com) to provide a streamlined development experience. -This implementation is different from the existing -[Envbuilder-based Dev Containers](../../admin/templates/managing-templates/devcontainers/index.md) -offering. - ## Prerequisites - Coder version 2.24.0 or later -- Coder CLI version 2.24.0 or later -- **Linux or macOS workspace**, Dev Containers are not supported on Windows -- A template with: - - Dev Containers integration enabled - - A Docker-compatible workspace image -- Appropriate permissions to execute Docker commands inside your workspace +- Docker available inside your workspace +- The `@devcontainers/cli` installed in your workspace -## How It Works - -The Dev Containers integration utilizes the `devcontainer` command from -[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage Dev -Containers within your Coder workspace. -This command provides comprehensive functionality for creating, starting, and managing Dev Containers. - -Dev environments are configured through a standard `devcontainer.json` file, -which allows for extensive customization of your development setup. - -When a workspace with the Dev Containers integration starts: - -1. The workspace initializes the Docker environment. -1. The integration detects repositories with a `.devcontainer` directory or a - `devcontainer.json` file. -1. The integration builds and starts the Dev Container based on the - configuration. -1. Your workspace automatically detects the running Dev Container. +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) +for setup details. ## Features -### Available Now +- Automatic dev container detection from repositories +- Seamless container startup during workspace initialization +- Change detection with outdated status indicator +- On-demand container rebuild via dashboard button +- Integrated IDE experience with VS Code +- Direct SSH access to containers +- Automatic port detection -- Automatic Dev Container detection from repositories -- Seamless Dev Container startup during workspace initialization -- Dev Container change detection and dirty state indicators -- On-demand Dev Container recreation via rebuild button -- Integrated IDE experience in Dev Containers with VS Code -- Direct service access in Dev Containers -- SSH access to Dev Containers -- Automatic port detection for container ports +## Getting started + +### Add a devcontainer.json + +Add a `devcontainer.json` file to your repository. This file defines your +development environment. You can place it in: + +- `.devcontainer/devcontainer.json` (recommended) +- `.devcontainer.json` (root of repository) +- `.devcontainer//devcontainer.json` (for multiple configurations) + +The third option allows monorepos to define multiple dev container +configurations in separate sub-folders. See the +[Dev Container specification](https://containers.dev/implementors/spec/#devcontainerjson) +for details. + +Here's a minimal example: + +```json +{ + "name": "My Dev Container", + "image": "mcr.microsoft.com/devcontainers/base:ubuntu" +} +``` + +For more configuration options, see the +[Dev Container specification](https://containers.dev/). + +### Start your dev container + +Coder automatically discovers dev container configurations in your repositories +and displays them in your workspace dashboard. From there, you can start a dev +container with a single click. + +If your template administrator has configured automatic startup (via the +`coder_devcontainer` Terraform resource or autostart settings), your dev +container will build and start automatically when the workspace starts. + +### Connect to your dev container + +Once running, your dev container appears as a sub-agent in your workspace +dashboard. You can connect via: + +- **Web terminal** in the Coder dashboard +- **SSH** using `coder ssh .` +- **VS Code** using the "Open in VS Code Desktop" button + +See [Working with dev containers](./working-with-dev-containers.md) for detailed +connection instructions. + +## How it works + +The Dev Containers integration uses the `devcontainer` command from +[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage +containers within your Coder workspace. + +When a workspace with Dev Containers integration starts: + +1. The workspace initializes the Docker environment. +1. The integration detects repositories with dev container configurations. +1. Detected dev containers appear in the Coder dashboard. +1. If auto-start is configured (via `coder_devcontainer` or autostart settings), + the integration builds and starts the dev container automatically. +1. Coder creates a sub-agent for the running container, enabling direct access. + +Without auto-start, users can manually start discovered dev containers from the +dashboard. + +### Agent naming + +Each dev container gets its own agent name, derived from the workspace folder +path. For example, a dev container with workspace folder `/home/coder/my-app` +will have an agent named `my-app`. + +Agent names are sanitized to contain only lowercase alphanumeric characters and +hyphens. You can also set a +[custom agent name](./customizing-dev-containers.md#custom-agent-name) +in your `devcontainer.json`. ## Limitations -The Dev Containers integration has the following limitations: +- **Linux and macOS only** — Dev Containers are not supported on Windows + workspaces +- Changes to `devcontainer.json` require manual rebuild using the dashboard + button +- The `forwardPorts` property in `devcontainer.json` with `host:port` syntax + (e.g., `"db:5432"`) for Docker Compose sidecar containers is not yet + supported. For single-container dev containers, use `coder port-forward` to + access ports directly on the sub-agent. +- Some advanced dev container features may have limited support -- **Not supported on Windows** -- Changes to the `devcontainer.json` file require manual container recreation - using the rebuild button -- Some Dev Container features may not work as expected +> [!NOTE] +> If your template uses Envbuilder rather than Docker-based dev containers, see +> the [Envbuilder documentation](../../admin/templates/managing-templates/envbuilder/index.md). -## Comparison with Envbuilder-based Dev Containers +## Next steps -| Feature | Dev Containers Integration | Envbuilder Dev Containers | -|----------------|----------------------------------------|----------------------------------------------| -| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder | -| Target users | Individual developers | Platform teams and administrators | -| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder | -| Management | User-controlled | Admin-controlled | -| Requirements | Docker access in workspace | Compatible with more restricted environments | - -Choose the appropriate solution based on your team's needs and infrastructure -constraints. For additional details on Envbuilder's Dev Container support, see -the -[Envbuilder Dev Container spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md). - -## Next Steps - -- Explore the [Dev Container specification](https://containers.dev/) to learn - more about advanced configuration options -- Read about [Dev Container features](https://containers.dev/features) to - enhance your development environment -- Check the - [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers) - for IDE-specific features +- [Working with dev containers](./working-with-dev-containers.md) — SSH, IDE + integration, and port forwarding +- [Customizing dev containers](./customizing-dev-containers.md) — Custom agent + names, apps, and display options +- [Troubleshooting dev containers](./troubleshooting-dev-containers.md) — + Diagnose common issues +- [Dev Container specification](https://containers.dev/) — Advanced + configuration options +- [Dev Container features](https://containers.dev/features) — Enhance your + environment with pre-built tools diff --git a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md index ca27516a81..c5acb79b2c 100644 --- a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md +++ b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md @@ -1,6 +1,6 @@ # Troubleshooting dev containers -## Dev Container Not Starting +## Dev container not starting If your dev container fails to start: @@ -10,7 +10,108 @@ If your dev container fails to start: - `/tmp/coder-startup-script.log` - `/tmp/coder-script-[script_id].log` -1. Verify that Docker is running in your workspace. -1. Ensure the `devcontainer.json` file is valid. +1. Verify Docker is available in your workspace (see below). +1. Ensure the `devcontainer.json` file is valid JSON. 1. Check that the repository has been cloned correctly. 1. Verify the resource limits in your workspace are sufficient. + +## Docker not available + +Dev containers require Docker, either via a running daemon (Docker-in-Docker) or +a mounted socket from the host. Your template determines which approach is used. + +**If using Docker-in-Docker**, check that the daemon is running: + +```console +sudo service docker status +sudo service docker start # if not running +``` + +**If using a mounted socket**, verify the socket exists and is accessible: + +```console +ls -la /var/run/docker.sock +docker ps # test access +``` + +If you get permission errors, your user may need to be in the `docker` group. + +## Finding your dev container agent + +Use `coder show` to list all agents in your workspace, including dev container +sub-agents: + +```console +coder show +``` + +The agent name is derived from the workspace folder path. For details on how +names are generated, see [Agent naming](./index.md#agent-naming). + +## SSH connection issues + +If `coder ssh .` fails: + +1. Verify the agent name using `coder show `. +1. Check that the dev container is running: + + ```console + docker ps + ``` + +1. Check the workspace agent logs for container-related errors: + + ```console + grep -i container /tmp/coder-agent.log + ``` + +## VS Code connection issues + +VS Code connects to dev containers through the Coder extension. The extension +uses the sub-agent information to route connections through the parent workspace +agent to the dev container. If VS Code fails to connect: + +1. Ensure you have the latest Coder VS Code extension. +1. Verify the dev container is running in the Coder dashboard. +1. Check the parent workspace agent is healthy. +1. Try restarting the dev container from the dashboard. + +## Dev container features not working + +If features from your `devcontainer.json` aren't being applied: + +1. Rebuild the container to ensure features are installed fresh. +1. Check the container build output for feature installation errors. +1. Verify the feature reference format is correct: + + ```json + { + "features": { + "ghcr.io/devcontainers/features/node:1": {} + } + } + ``` + +## Slow container startup + +If your dev container takes a long time to start: + +1. **Use a pre-built image** instead of building from a Dockerfile. This avoids + the image build step, though features and lifecycle scripts still run. +1. **Minimize features**. Each feature executes as a separate Docker layer + during the image build, which is typically the slowest part. Changing + `devcontainer.json` invalidates the layer cache, causing features to + reinstall on rebuild. +1. **Check lifecycle scripts**. Commands in `postStartCommand` run on every + container start. Commands in `postCreateCommand` run once per build, so + they execute again after each rebuild. + +## Getting more help + +If you continue to experience issues: + +1. Collect logs from `/tmp/coder-agent.log` (both workspace and container). +1. Note the exact error messages. +1. Check [Coder GitHub issues](https://github.com/coder/coder/issues) for + similar problems. +1. Contact your Coder administrator for template-specific issues. diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md index a4257f91d4..b5a1d107ac 100644 --- a/docs/user-guides/devcontainers/working-with-dev-containers.md +++ b/docs/user-guides/devcontainers/working-with-dev-containers.md @@ -5,93 +5,151 @@ visual representation of the running environment: ![Dev container integration in Coder dashboard](../../images/user-guides/devcontainers/devcontainer-agent-ports.png) -## SSH Access +## SSH access -You can SSH into your dev container directly using the Coder CLI: +Each dev container has its own agent name, derived from the workspace folder +(e.g., `/home/coder/my-project` becomes `my-project`). You can find agent names +in your workspace dashboard, or see +[Agent naming](./index.md#agent-naming) for details on how names are generated. + +### Using the Coder CLI + +The simplest way to SSH into a dev container is using `coder ssh` with the +workspace and agent name: ```console -coder ssh --container keen_dijkstra my-workspace +coder ssh . ``` -> [!NOTE] -> -> SSH access is not yet compatible with the `coder config-ssh` command for use -> with OpenSSH. You would need to manually modify your SSH config to include the -> `--container` flag in the `ProxyCommand`. +For example, to connect to a dev container with agent name `my-project` in +workspace `my-workspace`: -## Web Terminal Access +```console +coder ssh my-workspace.my-project +``` + +To SSH into the main workspace agent instead of the dev container: + +```console +coder ssh my-workspace +``` + +### Using OpenSSH (config-ssh) + +You can also use standard OpenSSH tools after generating SSH config entries with +`coder config-ssh`: + +```console +coder config-ssh +``` + +This creates a wildcard SSH host entry that matches all your workspaces and +their agents, including dev container sub-agents. You can then connect using: + +```console +ssh my-project.my-workspace.me.coder +``` + +The default hostname suffix is `.coder`. If your organization uses a different +suffix, adjust the hostname accordingly. The suffix can be configured via +[`coder config-ssh --hostname-suffix`](../../reference/cli/config-ssh.md) or +by your deployment administrator. + +This method works with any SSH client, IDE remote extensions, `rsync`, `scp`, +and other tools that use SSH. + +## Web terminal access Once your workspace and dev container are running, you can use the web terminal in the Coder interface to execute commands directly inside the dev container. ![Coder web terminal with dev container](../../images/user-guides/devcontainers/devcontainer-web-terminal.png) -## IDE Integration (VS Code) +## IDE integration (VS Code) You can open your dev container directly in VS Code by: -1. Selecting "Open in VS Code Desktop" from the Coder web interface -2. Using the Coder CLI with the container flag: +1. Selecting **Open in VS Code Desktop** from the dev container agent in the + Coder web interface. +1. Using the Coder CLI: -```console -coder open vscode --container keen_dijkstra my-workspace -``` + ```console + coder open vscode . + ``` -While optimized for VS Code, other IDEs with dev containers support may also + For example: + + ```console + coder open vscode my-workspace.my-project + ``` + +VS Code will automatically detect the dev container environment and connect +appropriately. + +While optimized for VS Code, other IDEs with dev container support may also work. -## Port Forwarding +## Port forwarding -During the early access phase, port forwarding is limited to ports defined via +Since dev containers run as sub-agents, you can forward ports directly to them +using standard Coder port forwarding: + +```console +coder port-forward . --tcp 8080 +``` + +For example, to forward port 8080 from a dev container with agent name +`my-project`: + +```console +coder port-forward my-workspace.my-project --tcp 8080 +``` + +This forwards port 8080 on your local machine directly to port 8080 in the dev +container. Coder also automatically detects ports opened inside the container. + +### Exposing ports on the parent workspace + +If you need to expose dev container ports through the parent workspace agent +(rather than the sub-agent), you can use the [`appPort`](https://containers.dev/implementors/json_reference/#image-specific) -in your `devcontainer.json` file. - -> [!NOTE] -> -> Support for automatic port forwarding via the `forwardPorts` property in -> `devcontainer.json` is planned for a future release. - -For example, with this `devcontainer.json` configuration: +property in your `devcontainer.json`: ```json { - "appPort": ["8080:8080", "4000:3000"] + "appPort": ["8080:8080", "4000:3000"] } ``` -You can forward these ports to your local machine using: +This maps container ports to the parent workspace, which can then be forwarded +using the main workspace agent. -```console -coder port-forward my-workspace --tcp 8080,4000 -``` +## Dev container features -This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port -4000 (local) -> 4000 (agent) -> 3000 (dev container). - -## Dev Container Features - -You can use standard dev container features in your `devcontainer.json` file. -Coder also maintains a +You can use standard [dev container features](https://containers.dev/features) +in your `devcontainer.json` file. Coder also maintains a [repository of features](https://github.com/coder/devcontainer-features) to enhance your development experience. -Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server). - -To use the code-server feature, add the following to your `devcontainer.json`: +For example, the +[code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server) +feature from the [Coder features repository](https://github.com/coder/devcontainer-features): ```json { - "features": { - "ghcr.io/coder/devcontainer-features/code-server:1": { - "port": 13337, - "host": "0.0.0.0" - } - }, - "appPort": ["13337:13337"] + "features": { + "ghcr.io/coder/devcontainer-features/code-server:1": { + "port": 13337, + "host": "0.0.0.0" + } + } } ``` -> [!NOTE] -> -> Remember to include the port in the `appPort` section to ensure proper port -> forwarding. +## Rebuilding dev containers + +When you modify your `devcontainer.json`, you need to rebuild the container for +changes to take effect. Coder detects changes and shows an **Outdated** status +next to the dev container. + +Click **Rebuild** to recreate your dev container with the updated configuration. diff --git a/docs/user-guides/index.md b/docs/user-guides/index.md index 92040b4beb..ab636eaf77 100644 --- a/docs/user-guides/index.md +++ b/docs/user-guides/index.md @@ -7,7 +7,7 @@ These are intended for end-user flows only. If you are an administrator, please refer to our docs on configuring [templates](../admin/index.md) or the [control plane](../admin/index.md). -Check out our [early access features](../install/releases/feature-stages.md) for upcoming -functionality, including [Dev Containers integration](../user-guides/devcontainers/index.md). +Check out [Dev Containers integration](./devcontainers/index.md) for running +containerized development environments in your Coder workspace.