From ea9f003cdde8e98047991bed884f6bde20706341 Mon Sep 17 00:00:00 2001 From: Mathias Fredriksson Date: Tue, 9 Dec 2025 16:37:19 +0200 Subject: [PATCH] docs: clarify dev containers entry point and reduce callouts (#21188) The user guide jumped straight into integration details without explaining what dev containers are. Now it opens with a brief orientation linking to the spec, then explains this guide covers the Docker-based approach. Converted several NOTE callouts to prose where they were just cross-references or stacked unnecessarily. The Envbuilder index note was reframed to lead with its strengths rather than "we recommend the other thing." Also updates platform support to Linux only per current status. Refs #21157 --- .../devcontainers/envbuilder/index.md | 13 +++++---- .../integrations/devcontainers/integration.md | 26 ++++++------------ docs/manifest.json | 2 +- docs/user-guides/devcontainers/index.md | 27 +++++++++---------- 4 files changed, 28 insertions(+), 40 deletions(-) diff --git a/docs/admin/integrations/devcontainers/envbuilder/index.md b/docs/admin/integrations/devcontainers/envbuilder/index.md index 74b9b47d98..9b4bc0c9df 100644 --- a/docs/admin/integrations/devcontainers/envbuilder/index.md +++ b/docs/admin/integrations/devcontainers/envbuilder/index.md @@ -6,13 +6,12 @@ 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. +Envbuilder is well-suited for Kubernetes-native deployments without privileged +containers, environments where Docker is unavailable or restricted, and +workflows where administrators need infrastructure-level control over image +builds, caching, and security scanning. For workspaces with Docker available, +the [Dev Containers Integration](../integration.md) offers container management +with dashboard visibility and multi-container support. Dev containers provide developers with increased autonomy and control over their Coder cloud development environments. diff --git a/docs/admin/integrations/devcontainers/integration.md b/docs/admin/integrations/devcontainers/integration.md index 1255890500..2e11134ff0 100644 --- a/docs/admin/integrations/devcontainers/integration.md +++ b/docs/admin/integrations/devcontainers/integration.md @@ -1,14 +1,13 @@ # Configure a template for Dev Containers -> [!NOTE] -> For environments without Docker, see [Envbuilder](./envbuilder/index.md) as an alternative. +This guide covers the Dev Containers Integration, which uses Docker. For +environments without Docker, see [Envbuilder](./envbuilder/index.md) as an +alternative. To enable Dev Containers in workspaces, configure your template with the Dev Containers modules and configurations outlined in this doc. -> [!NOTE] -> -> Dev Containers require a **Linux or macOS workspace**. Windows is not supported. +Dev Containers are currently not supported in Windows or macOS workspaces. ## Configuration Modes @@ -66,19 +65,10 @@ resource "coder_devcontainer" "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. +The `workspace_folder` attribute must point to a valid project folder containing +a `devcontainer.json` file. Consider using the +[`git-clone`](https://registry.coder.com/modules/git-clone) module to ensure +your repository is cloned 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 diff --git a/docs/manifest.json b/docs/manifest.json index 0d75666899..709d67e2ca 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -321,7 +321,7 @@ "icon_path": "./images/icons/circle-dot.svg" }, { - "title": "Dev Containers Integration", + "title": "Dev Containers", "description": "Run containerized development environments in your Coder workspace using the dev containers specification.", "path": "./user-guides/devcontainers/index.md", "icon_path": "./images/icons/container.svg", diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md index 42106757b8..a00a5e30e2 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -1,16 +1,15 @@ -# Dev Containers Integration +# Dev Containers -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. +[Dev containers](https://containers.dev/) define your development environment +as code using a `devcontainer.json` file. Coder's Dev Containers integration +uses the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and +[Docker](https://www.docker.com) to seamlessly build and run these containers, +with management in your dashboard. -> [!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. +This guide covers the Dev Containers integration. For workspaces without Docker, +administrators can configure +[Envbuilder](../../admin/integrations/devcontainers/envbuilder/index.md) instead, +which builds the workspace image itself from your dev container configuration. ## Prerequisites @@ -20,7 +19,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 +templates with Dev Containers support include both. See [Configure a template for dev containers](../../admin/integrations/devcontainers/integration.md) for setup details. @@ -115,8 +114,8 @@ in your `devcontainer.json`. ## Limitations -- **Linux and macOS only** — Dev Containers are not supported on Windows - workspaces +- **Linux only**: Dev Containers are currently not supported in Windows or + macOS workspaces - Changes to `devcontainer.json` require manual rebuild using the dashboard button - The `forwardPorts` property in `devcontainer.json` with `host:port` syntax