diff --git a/docs/about/contributing/backend.md b/docs/about/contributing/backend.md index ad5d91bcda879..cfc70af53e74a 100644 --- a/docs/about/contributing/backend.md +++ b/docs/about/contributing/backend.md @@ -49,7 +49,7 @@ Coder's backend is built using a collection of robust, modern Go libraries and i The Coder backend is organized into multiple packages and directories, each with a specific purpose. Here's a high-level overview of the most important ones: -* [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports DevContainers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto). +* [agent](https://github.com/coder/coder/tree/main/agent): core logic of a workspace agent, supports dev containers, remote SSH, startup/shutdown script execution. Protobuf definitions for DRPC communication with `coderd` are kept in [proto](https://github.com/coder/coder/tree/main/agent/proto). * [cli](https://github.com/coder/coder/tree/main/cli): CLI interface for `coder` command built on [coder/serpent](https://github.com/coder/serpent). Input controls are defined in [cliui](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/cliui), and [testdata](https://github.com/coder/coder/tree/docs-backend-contrib-guide/cli/testdata) contains golden files for common CLI calls * [cmd](https://github.com/coder/coder/tree/main/cmd): entry points for CLI and services, including `coderd` * [coderd](https://github.com/coder/coder/tree/main/coderd): the main API server implementation with [chi](https://github.com/go-chi/chi) endpoints @@ -72,7 +72,7 @@ The Coder backend is organized into multiple packages and directories, each with * [dbpurge](https://github.com/coder/coder/tree/main/coderd/database/dbpurge): simple wrapper for periodic database cleanup operations * [migrations](https://github.com/coder/coder/tree/main/coderd/database/migrations): an ordered list of up/down database migrations, use `./create_migration.sh my_migration_name` to modify the database schema * [pubsub](https://github.com/coder/coder/tree/main/coderd/database/pubsub): PubSub implementation using PostgreSQL and in-memory drop-in replacement - * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/blob/docs-backend-contrib-guide/coderd/database/queries.sql.go) + * [queries](https://github.com/coder/coder/tree/main/coderd/database/queries): contains SQL files with queries, `sqlc` compiles them to [Go functions](https://github.com/coder/coder/tree/main/coderd/database/queries.sql.go) * [sqlc.yaml](https://github.com/coder/coder/tree/main/coderd/database/sqlc.yaml): defines mappings between SQL types and custom Go structures * [codersdk](https://github.com/coder/coder/tree/main/codersdk): user-facing API entities used by CLI and site to communicate with `coderd` endpoints * [dogfood](https://github.com/coder/coder/tree/main/dogfood): Terraform definition of the dogfood cluster deployment diff --git a/docs/admin/templates/extending-templates/advanced-dev-containers.md b/docs/admin/templates/extending-templates/advanced-dev-containers.md new file mode 100644 index 0000000000000..d84941c8f1111 --- /dev/null +++ b/docs/admin/templates/extending-templates/advanced-dev-containers.md @@ -0,0 +1,100 @@ +# Advanced Dev Container Configuration + +This page extends the [dev containers documentation](./devcontainers.md) with patterns for multiple dev containers, +user-controlled startup, repository selection, and infrastructure tuning. + +## Run Multiple Dev Containers + +Run independent dev containers in the same workspace so each component appears as its own agent. + +In this example, there are two: repositories called `frontend` and `backend`: + +```terraform +# Clone each repo +module "git-clone-frontend" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/git-clone/coder" + + agent_id = coder_agent.main.id + url = "https://github.com/your-org/frontend.git" +} + +module "git-clone-backend" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/git-clone/coder" + + agent_id = coder_agent.main.id + url = "https://github.com/your-org/backend.git" +} + +# Dev container resources +resource "coder_devcontainer" "frontend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = module.git-clone-frontend[0].repo_dir +} + +resource "coder_devcontainer" "backend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = module.git-clone-backend[0].repo_dir +} +``` + +Each dev container appears as a separate agent, so developers can connect to each separately. + +## Conditional Startup + +Use `coder_parameter` booleans to let workspace creators choose which dev containers start automatically, +reducing resource usage for unneeded components: + +```terraform +data "coder_parameter" "autostart_frontend" { + type = "bool" + name = "Autostart frontend container" + default = true + mutable = true + order = 3 +} + +resource "coder_devcontainer" "frontend" { + count = data.coder_parameter.autostart_frontend.value ? data.coder_workspace.me.start_count : 0 + agent_id = coder_agent.main.id + workspace_folder = module.git-clone-frontend[0].repo_dir +} +``` + +## Repository-selection Patterns + +Prompt users to pick a repository or team at workspace creation time and clone the selected repo(s) automatically into the workspace: + +1. Add a parameter to the template: + + ```terraform + data "coder_parameter" "project" { + name = "project" + display_name = "Choose a project" + type = "string" + default = "https://github.com/coder/coder.git" + + option { + name = "coder/coder" + value = "https://github.com/coder/coder.git" + } + option { + name = "terraform-provider-coder" + value = "https://github.com/coder/terraform-provider-coder.git" + } + } + ``` + +1. Change the `git-clone` module to accept the `value` as the `url`: + + ```terraform + module "git-clone" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/git-clone/coder" + agent_id = coder_agent.main.id + url = data.coder_parameter.project.value + } + ``` diff --git a/docs/admin/templates/extending-templates/dev-containers-envbuilder.md b/docs/admin/templates/extending-templates/dev-containers-envbuilder.md new file mode 100644 index 0000000000000..4a8d53091b0dd --- /dev/null +++ b/docs/admin/templates/extending-templates/dev-containers-envbuilder.md @@ -0,0 +1,23 @@ +# Choose an Approach To Dev Containers + +Coder supports two independent ways to run Dev Containers inside a workspace. + +Both implement the [Dev Container specification](https://containers.dev/), but they differ in how the container is built, +who controls it, and which runtime requirements exist. + +Use this page to decide which path fits your project or platform needs. + +## Options at a Glance + +| Capability / Trait | Dev Containers integration | Envbuilder | +|------------------------------------------|--------------------------------------------|-------------------------------------------| +| How it's built | `@devcontainers/cli` and Docker | Envbuilder transforms the workspace image | +| Docker-in-Docker? | Yes (parent workspace and child container) | No (modifies the parent container) | +| Multiple dev containers per workspace | Yes | No | +| Rebuild when `devcontainer.json` changes | Yes - user-initiated | Requires full workspace restart | + +## Related Reading + +- [Dev Containers integration](./devcontainers.md) +- [Dev Containers specification](https://containers.dev/) +- [Envbuilder on GitHub](https://github.com/coder/envbuilder) diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md index d4284bf48efde..6213d89d3a3de 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -1,126 +1,340 @@ -# Configure a template for dev containers +# Configure a Template for Dev Containers -To enable dev containers in workspaces, configure your template with the dev containers +Dev containers provide consistent, reproducible development environments using the +[Development Containers specification](https://containers.dev/). +Coder's dev container support allows developers to work in fully configured environments with their preferred tools and extensions. + +To add dev container support to a workspace, [configure your template](../creating-templates.md) with the dev containers modules and configurations outlined in this doc. +## Why Use Dev Containers + +Dev containers improve consistency across environments by letting developers define their development setup within +the code repository. + +When integrated with Coder templates, dev containers provide: + +- **Project-specific environments**: Each repository can define its own tools, extensions, and configuration. +- **Faster start times**: Developers start workspace with fully configured environments without additional installation. +- **Consistency across teams**: Everyone works in identical environments regardless of their local machine. +- **Version-controlled environments**: Development environment changes are tracked alongside code changes. + +The Dev Container integration replaces the legacy Envbuilder integration. +Visit [Choose an approach to Dev Containers](./dev-containers-envbuilder.md) for more information about how they compare. + +## Prerequisites + +- Dev containers require Docker to build and run containers inside the workspace. + + Ensure your workspace infrastructure has Docker configured with container creation permissions and sufficient resources. + + If it doesn't, follow the steps in [Docker in workspaces](./docker-in-workspaces.md). + +- The `devcontainers-cli` module requires npm. + + - You can use an image that already includes npm, such as `codercom/enterprise-node:ubuntu`. + ## 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: +to install `devcontainers/cli` in your workspace: ```terraform module "devcontainers-cli" { - count = data.coder_workspace.me.start_count - source = "dev.registry.coder.com/modules/devcontainers-cli/coder" - agent_id = coder_agent.dev.id + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/devcontainers-cli/coder" + agent_id = coder_agent.main.id } ``` -Alternatively, install the devcontainer CLI manually in your base image. +Alternatively, you can install `@devcontainer/cli` manually in your base image: -## Configure Automatic Dev Container Startup +```shell +RUN npm install -g @devcontainers/cli +``` -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: +## Configure the Agent for Docker Support + +Your Coder agent needs proper configuration to support Docker and dev containers: + +```terraform +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" + + # Ensure Docker starts before the agent considers the workspace ready + startup_script_behavior = "blocking" + startup_script = "sudo service docker start" + + # Properly shut down Docker when the workspace stops + shutdown_script = "sudo service docker stop" +} +``` + +The `blocking` behavior ensures Docker is fully started before the workspace is considered ready, which is critical for dev containers to function correctly. + +## Define the Dev Container Resource + +Use the git-clone module to provide repository access and define the dev container: + +```terraform +module "git-clone" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/git-clone/coder" + agent_id = coder_agent.main.id + url = "https://github.com/example/repository.git" + base_dir = "" # defaults to $HOME +} + +resource "coder_devcontainer" "repository" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = module.git-clone[0].repo_dir # Points to the cloned repository +} +``` + +The `repo_dir` output from the git-clone module provides the path to the cloned repository. + +### If you're not using the git-clone module + +If you need to point to a pre-existing directory or have another way of provisioning repositories, specify the directory that contains the dev container configuration: ```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" + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/project" # Path to a folder with devcontainer.json } ``` > [!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. - - +> The `workspace_folder` attribute must specify the location of the dev container's workspace and should point to a +> valid project directory that contains a `devcontainer.json` file or `.devcontainer` directory. -> [!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. +## Create the Docker Container Resource -## Enable Dev Containers Integration +Configure the Docker container to run the Coder agent and enable Docker-in-Docker capabilities required for dev containers. -To enable the dev containers integration in your workspace, you must set the -`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your -workspace container: +This example uses the `sysbox-runc` runtime for secure container isolation. +If sysbox isn't available in your environment, consult [Docker in workspaces](./docker-in-workspaces.md) for alternatives. ```terraform resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count - image = "codercom/oss-dogfood:latest" + + # Base image - this example uses one with npm pre-installed + image = "codercom/enterprise-node:ubuntu" + + # Create a unique container name to avoid conflicts + name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" + + # Use sysbox-runc for secure Docker-in-Docker + runtime = "sysbox-runc" + + # Start the Coder agent when the container starts + entrypoint = ["sh", "-c", coder_agent.main.init_script] + + # Configure agent authentication env = [ - "CODER_AGENT_DEVCONTAINERS_ENABLE=true", - # ... Other environment variables. + "CODER_AGENT_TOKEN=${coder_agent.main.token}", + "CODER_AGENT_URL=${data.coder_workspace.me.access_url}" ] - # ... Other container configuration. } ``` -This environment variable is required for the Coder agent to detect and manage -dev containers. Without it, the agent will not attempt to start or connect to -dev containers even if the `coder_devcontainer` resource is defined. +### Agent naming + +Coder names dev container agents in this order: + +1. `customizations.coder.name` in `devcontainer.json` +1. Project directory name (name of folder containing `devcontainer.json` or `.devcontainer` folder) +1. If the project directory name is already taken, the name is expanded to include the parent folder. + + For example, if the path is `/home/coder/some/project` and `project` is taken, then the agent is `some-project`. + +## Add Dev Container Features -## Complete Template Example +Enhance your dev container experience with additional features. +For more advanced use cases, consult the [advanced dev containers doc](./advanced-dev-containers.md). -Here's a simplified template example that enables the dev containers -integration: +### Custom applications + +Add apps to the dev container workspace resource for one-click access: + +```terraform + "coder": { + "apps": [ + { + "slug": "cursor", + "displayName": "Cursor", + "url": "cursor://coder.coder-remote/openDevContainer?owner=${localEnv:CODER_WORKSPACE_OWNER_NAME}&workspace=${localEnv:CODER_WORKSPACE_NAME}&agent=${localEnv:CODER_WORKSPACE_PARENT_AGENT_NAME}&url=${localEnv:CODER_URL}&token=$SESSION_TOKEN&devContainerName=${localEnv:CONTAINER_ID}&devContainerFolder=${containerWorkspaceFolder}&localWorkspaceFolder=${localWorkspaceFolder}", + "external": true, + "icon": "/icon/cursor.svg", + "order": 1 + }, +``` + +
Expand for a full example: + +This is an excerpt from the [.devcontainer.json](https://github.com/coder/coder/blob/main/.devcontainer/devcontainer.json) in the Coder repository: + +```terraform +resource "coder_devcontainer" "my-repository" { +... +{ + "customizations": { + ... + "coder": { + "apps": [ + { + "slug": "cursor", + "displayName": "Cursor", + "url": "cursor://coder.coder-remote/openDevContainer?owner=${localEnv:CODER_WORKSPACE_OWNER_NAME}&workspace=${localEnv:CODER_WORKSPACE_NAME}&agent=${localEnv:CODER_WORKSPACE_PARENT_AGENT_NAME}&url=${localEnv:CODER_URL}&token=$SESSION_TOKEN&devContainerName=${localEnv:CONTAINER_ID}&devContainerFolder=${containerWorkspaceFolder}&localWorkspaceFolder=${localWorkspaceFolder}", + "external": true, + "icon": "/icon/cursor.svg", + "order": 1 + }, + // Reproduce `code-server` app here from the code-server + // feature so that we can set the correct folder and order. + // Currently, the order cannot be specified via option because + // we parse it as a number whereas variable interpolation + // results in a string. Additionally we set health check which + // is not yet set in the feature. + { + "slug": "code-server", + "displayName": "code-server", + "url": "http://${localEnv:FEATURE_CODE_SERVER_OPTION_HOST:127.0.0.1}:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}/?folder=${containerWorkspaceFolder}", + "openIn": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPOPENIN:slim-window}", + "share": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPSHARE:owner}", + "icon": "/icon/code.svg", + "group": "${localEnv:FEATURE_CODE_SERVER_OPTION_APPGROUP:Web Editors}", + "order": 3, + "healthCheck": { + "url": "http://${localEnv:FEATURE_CODE_SERVER_OPTION_HOST:127.0.0.1}:${localEnv:FEATURE_CODE_SERVER_OPTION_PORT:8080}/healthz", + "interval": 5, + "threshold": 2 + }, + { + "slug": "windsurf", + "displayName": "Windsurf Editor", + "url": "windsurf://coder.coder-remote/openDevContainer?owner=${localEnv:CODER_WORKSPACE_OWNER_NAME}&workspace=${localEnv:CODER_WORKSPACE_NAME}&agent=${localEnv:CODER_WORKSPACE_PARENT_AGENT_NAME}&url=${localEnv:CODER_URL}&token=$SESSION_TOKEN&devContainerName=${localEnv:CONTAINER_ID}&devContainerFolder=${containerWorkspaceFolder}&localWorkspaceFolder=${localWorkspaceFolder}", + "external": true, + "icon": "/icon/windsurf.svg", + "order": 3 + }, + { + "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": 4 + }, + } + ] + } + }, +} +``` + +
+ +### Multiple dev containers + +```terraform +resource "coder_devcontainer" "frontend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/frontend" +} +resource "coder_devcontainer" "backend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/backend" +} +``` + +## Example Docker Dev Container Template + +
Expand for the full file: ```terraform terraform { required_providers { - coder = { source = "coder/coder" } + 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" +resource "coder_agent" "main" { + os = "linux" + arch = "amd64" startup_script_behavior = "blocking" - startup_script = "sudo service docker start" - shutdown_script = "sudo service docker stop" - # ... + startup_script = "sudo service docker start" + shutdown_script = "sudo service docker stop" } module "devcontainers-cli" { - count = data.coder_workspace.me.start_count - source = "dev.registry.coder.com/modules/devcontainers-cli/coder" - agent_id = coder_agent.dev.id + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/devcontainers-cli/coder" + agent_id = coder_agent.main.id +} + +module "git-clone" { + count = data.coder_workspace.me.start_count + source = "registry.coder.com/modules/git-clone/coder" + agent_id = coder_agent.main.id + url = "https://github.com/coder/coder.git" + base_dir = "" # defaults to $HOME + depth = 1 # Use a shallow clone for faster startup } resource "coder_devcontainer" "my-repository" { - count = data.coder_workspace.me.start_count - agent_id = coder_agent.dev.id - workspace_folder = "/home/coder/my-repository" + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = module.git-clone[0].repo_dir } resource "docker_container" "workspace" { count = data.coder_workspace.me.start_count - image = "codercom/oss-dogfood:latest" + image = "codercom/enterprise-node:ubuntu" + name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}" + runtime = "sysbox-runc" + entrypoint = ["sh", "-c", coder_agent.main.init_script] env = [ - "CODER_AGENT_DEVCONTAINERS_ENABLE=true", - # ... Other environment variables. + "CODER_AGENT_TOKEN=${coder_agent.main.token}", + "CODER_AGENT_URL=${data.coder_workspace.me.access_url}" ] - # ... Other container configuration. } ``` +## Troubleshoot Common Issues + +### Disable dev containers integration + +To disable the dev containers integration in your workspace, set the `CODER_AGENT_DEVCONTAINERS_ENABLE=false` +environment variable before starting the agent. + +### Dev container does not start + +1. Confirm that the Docker daemon is running inside the workspace: + + ```shell + sudo service docker start && \ + docker ps + ``` + +1. Confirm the location of `devcontainer.json`. + +1. Check the agent logs for errors. + ## Next Steps +- [Advanced dev containers](./advanced-dev-containers.md) - [Dev Containers Integration](../../../user-guides/devcontainers/index.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 cc9a08cf26a25..85f2769e880bd 100644 --- a/docs/admin/templates/index.md +++ b/docs/admin/templates/index.md @@ -50,9 +50,6 @@ needs of different teams. 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). - [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/devcontainers/add-devcontainer.md index 5d2ac0a07f9e2..a14aa06048bd8 100644 --- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md +++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md @@ -1,14 +1,16 @@ -# Add a dev container template to Coder +# Add an Envbuilder Dev Container 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 -`devcontainer.json` specified in the repo. +This guide shows platform administrators how to add an Envbuilder dev container template to Coder. -You can create template files through the Coder dashboard, CLI, or you can -choose a template from the +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 `devcontainer.json` specified in the repo. + +This is a legacy implementation. + +For the Docker-based Dev Containers integration, follow the [Configure a template for dev containers](../../extending-templates/devcontainers.md) documentation instead. + +You can create template files through the Coder dashboard, CLI, or you can choose a template from the [Coder registry](https://registry.coder.com/templates):
@@ -118,7 +120,7 @@ their development environments: # … ``` -## Example templates +## Example Templates | Template | Description | |---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -132,7 +134,7 @@ Your template can prompt the user for a repo URL with ![Dev container parameter screen](../../../../images/templates/devcontainers.png) -## Dev container lifecycle scripts +## Dev container Lifecycle Scripts The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and `postStartCommand` lifecycle scripts are run each time the container is started. @@ -141,6 +143,7 @@ a user begins using the workspace. Lifecycle scripts are managed by project developers. -## Next steps +## Next Steps +- [Choose an approach to Dev Containers](../../extending-templates/devcontainers.md) - [Dev container security and caching](./devcontainer-security-caching.md) diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md index b8ba3bfddd21e..6d1cffa182ce0 100644 --- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md +++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md @@ -1,6 +1,10 @@ -# Dev container releases and known issues +# Envbuilder Dev Container Releases and Known Issues -## Release channels +Envbuilder is a legacy implementation of dev containers. + +For the Docker-based Dev Containers integration, follow the [Configure a template for dev containers](../../extending-templates/devcontainers.md) documentation instead. + +## Release Channels Envbuilder provides two release channels: @@ -18,7 +22,7 @@ Refer to the [Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more information and to submit feature requests or bug reports. -## Known issues +## Known Issues Visit the [Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md) diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md index a0ae51624fc6d..7ce5e06287a3c 100644 --- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md +++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md @@ -1,16 +1,16 @@ -# Dev container security and caching +# Envbuilder Dev Container 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. +Envbuilder can pull only pre-approved images and artifacts when you configure it with your enterprise proxies, +firewalls, and artifact managers. -## Configure registry authentication +## Configure Registry Authentication You may need to authenticate to your container registry, such as Artifactory, or Git provider such as GitLab, to use Envbuilder. See the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md) for more information. -## Layer and image caching +## Layer and Image Caching To improve build times, dev containers can be cached. There are two main forms of caching: @@ -60,7 +60,7 @@ If you are building your own Dev container template, you can consult the You may also wish to consult a [documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf). -## Next steps +## Next Steps - [Dev container releases and known issues](./devcontainer-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/devcontainers/index.md index a4ec140765a4c..e0a5eb7299e14 100644 --- a/docs/admin/templates/managing-templates/devcontainers/index.md +++ b/docs/admin/templates/managing-templates/devcontainers/index.md @@ -1,4 +1,4 @@ -# Dev containers +# Envbuilder Dev Containers A Development Container is an [open-source specification](https://containers.dev/implementors/spec/) for @@ -14,91 +14,18 @@ pre-approved by platform teams in registries like 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. +Envbuilder is a legacy implementation of 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. +For the Docker-based Dev Containers integration, follow the [Configure a template for dev containers](../../extending-templates/devcontainers.md) documentation instead. -### 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 +## Prerequisites -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. +An administrator should construct or choose a base image and create a template +that includes an Envbuilder container image `coder/envbuilder` before a developer team configures dev containers. -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. +Compare the differences between [Envbuilder and the Dev Containers integration](../../extending-templates/dev-containers-envbuilder.md). -## Devcontainer Features +## Dev Container Features [Dev container Features](https://containers.dev/implementors/features/) allow owners of a project to specify self-contained units of code and runtime @@ -119,4 +46,5 @@ 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 dev container template](./add-devcontainer.md) +- [Choose an approach to Dev Containers](../../extending-templates/dev-containers-envbuilder.md) diff --git a/docs/changelogs/v2.0.0.md b/docs/changelogs/v2.0.0.md index f74beaf14143c..7e20cc4ae55ce 100644 --- a/docs/changelogs/v2.0.0.md +++ b/docs/changelogs/v2.0.0.md @@ -100,7 +100,7 @@ Questions? Feel free to ask in [our Discord](https://discord.gg/coder) or email ### Bug fixes -- Do not wait for devcontainer template volume claim bound (#8539) (@Tirzono) +- Do not wait for dev container template volume claim bound (#8539) (@Tirzono) - Prevent repetition of template IDs in `template_usage_by_day` (#8693) (@mtojek) - Unify parameter validation errors (#8738) (@mtojek) diff --git a/docs/changelogs/v2.6.0.md b/docs/changelogs/v2.6.0.md index 5bf7c10992696..72798c109e55b 100644 --- a/docs/changelogs/v2.6.0.md +++ b/docs/changelogs/v2.6.0.md @@ -13,8 +13,8 @@ ![Light theme preview](https://raw.githubusercontent.com/coder/coder/main/docs/changelogs/images/light-theme.png) - Enable CSRF token header (#11283) (@Emyrk) - Add support for OAuth2 Applications (#11197) (@code-asher) -- Add AWS EC2 devcontainer template (#11248) (@matifali) -- Add Google Compute engine devcontainer template (#11246) (@matifali) +- Add AWS EC2 dev container template (#11248) (@matifali) +- Add Google Compute engine dev container template (#11246) (@matifali) ### Bug fixes diff --git a/docs/changelogs/v2.9.0.md b/docs/changelogs/v2.9.0.md index ec92da79028cb..d759b3d7e2402 100644 --- a/docs/changelogs/v2.9.0.md +++ b/docs/changelogs/v2.9.0.md @@ -126,7 +126,7 @@ The following features are hidden or disabled by default as we don't guarantee s - CLI: Ensure ssh cleanup happens on cmd error (@spikecurtis) - Dashboard: Display tooltip when selection is disabled (#12439) (@f0ssel) - Server: Add `--block-direct-connections` to wsproxies (#12182) (@coadler) -- Examples: Fix directory for devcontainer-docker template (#12453) (@alv67) +- Examples: Fix directory for dev container-docker template (#12453) (@alv67) - Dashboard: Make public menu item selectable (#12484) (@f0ssel) - Server: Stop holding Pubsub mutex while calling pq.Listener (#12518) (@spikecurtis) diff --git a/docs/manifest.json b/docs/manifest.json index 65555caa0df4f..a88ffc625308d 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -479,23 +479,23 @@ "path": "./admin/templates/managing-templates/change-management.md" }, { - "title": "Dev containers", - "description": "Learn about using development containers in templates", + "title": "Envbuilder Dev Containers", + "description": "Learn about using Envbuilder to manage development containers in templates", "path": "./admin/templates/managing-templates/devcontainers/index.md", "children": [ { - "title": "Add a dev container template", - "description": "How to add a dev container template to Coder", + "title": "Add an Envbuilder dev container template", + "description": "Use Envbuilder to add a dev container template to Coder", "path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md" }, { - "title": "Dev container security and caching", - "description": "Configure dev container authentication and caching", + "title": "Envbuilder dev container security and caching", + "description": "Configure dev container authentication and caching with Envbuilder", "path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md" }, { - "title": "Dev container releases and known issues", - "description": "Dev container releases and known issues", + "title": "Envbuilder dev container releases and known issues", + "description": "Envbuilder dev container releases and known issues", "path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md" } ] @@ -606,8 +606,20 @@ }, { "title": "Configure a template for dev containers", - "description": "How to use configure your template for dev containers", - "path": "./admin/templates/extending-templates/devcontainers.md" + "description": "How to configure your template for dev containers", + "path": "./admin/templates/extending-templates/devcontainers.md", + "children": [ + { + "title": "Advanced dev container configurations", + "description": "Enhance your dev container configurations with multiple containers, repo selection, monitoring, and more.", + "path": "./admin/templates/extending-templates/advanced-dev-containers.md" + }, + { + "title": "Choose an approach to Dev Containers", + "description": "How to choose the right Dev Container integration.", + "path": "./admin/templates/extending-templates/dev-containers-envbuilder.md" + } + ] }, { "title": "Process Logging", diff --git a/docs/user-guides/devcontainers/index.md b/docs/user-guides/devcontainers/index.md index ed817fe853416..a90128d8e88a1 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -1,25 +1,14 @@ # Dev Containers Integration -> [!NOTE] -> -> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature. -> -> While functional for testing and feedback, it may change significantly before general availability. - -The dev containers integration is an early access feature that 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. +The dev containers integration enables seamless creation and management of dev containers in Coder workspaces. + +This feature leverages [`@devcontainers/cli`](https://github.com/devcontainers/cli) and [Docker](https://www.docker.com) +to provide a streamlined development experience. ## Prerequisites -- Coder version 2.22.0 or later -- Coder CLI version 2.22.0 or later +- Coder version 2.24.0 or later +- Coder CLI version 2.24.0 or later - A template with: - Dev containers integration enabled - A Docker-compatible workspace image @@ -38,62 +27,42 @@ 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. The integration detects repositories with a `.devcontainer` directory or a `devcontainer.json` file. +1. The integration starts the dev container based on the template and `devcontainer.json`. 1. Your workspace automatically detects the running dev container. ## Features -### Available Now +### Detection and Lifecycle -- Automatic dev container detection from repositories -- Seamless dev container startup during workspace initialization -- Integrated IDE experience in dev containers with VS Code -- Direct service access in dev containers -- Limited SSH access to dev containers +- Automatic dev container detection from repositories. +- Change detection with rebuild prompts. +- Rebuild containers with one click from the Coder dashboard. -### Coming Soon +### Connectivity -- Dev container change detection -- On-demand dev container recreation -- Support for automatic port forwarding inside the container -- Full native SSH support to dev containers +- Full SSH access directly into dev containers (after running `coder config-ssh`): -## Limitations during Early Access + ```shell + ssh ..me.coder + ``` -During the early access phase, the dev containers integration has the following -limitations: + Example: -- Changes to the `devcontainer.json` file require manual container recreation -- Automatic port forwarding only works for ports specified in `appPort` -- SSH access requires using the `--container` flag -- Some devcontainer features may not work as expected + ```shell + ssh devcontainer.myworkspace.me.coder + ``` -These limitations will be addressed in future updates as the feature matures. +- Support for ports defined in the `appPort` property of your `devcontainer.json` file. -## Comparison with Envbuilder-based Dev Containers +## Known Limitations -| Feature | Dev Containers (Early Access) | 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 | +Currently, dev containers are not compatible with [prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md). -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 devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md). +If your template allows for prebuilt workspaces, do not select a prebuilt workspace if you plan to use a dev container. ## 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 +- [Dev Container specification](https://containers.dev/) +- [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers) +- [Choose an approach to Dev Containers](../../admin/templates/extending-templates/dev-containers-envbuilder.md) diff --git a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md index ca27516a81cc0..1b3b5da9858d8 100644 --- a/docs/user-guides/devcontainers/troubleshooting-dev-containers.md +++ b/docs/user-guides/devcontainers/troubleshooting-dev-containers.md @@ -1,6 +1,9 @@ # Troubleshooting dev containers -## Dev Container Not Starting +If you encounter issues with dev containers in your workspace, review the steps here as well as the dev containers +[user](./index.md) and [admin](../../admin/templates/extending-templates/devcontainers.md#troubleshoot-common-issues) documentation. + +## Container does not start If your dev container fails to start: @@ -13,4 +16,12 @@ If your dev container fails to start: 1. Verify that Docker is running in your workspace. 1. Ensure the `devcontainer.json` file is valid. 1. Check that the repository has been cloned correctly. -1. Verify the resource limits in your workspace are sufficient. +1. Ensure the workspace image has Node/npm and the `devcontainers-cli` module installed. +1. Verify that the resource limits in your workspace are sufficient. + +## Known Limitations + +Currently, dev containers are not compatible with the +[prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md). + +If your template allows for prebuilt workspaces, do not select a prebuilt workspace if you plan to use a dev container. diff --git a/docs/user-guides/devcontainers/working-with-dev-containers.md b/docs/user-guides/devcontainers/working-with-dev-containers.md index a4257f91d420e..08c85b883029e 100644 --- a/docs/user-guides/devcontainers/working-with-dev-containers.md +++ b/docs/user-guides/devcontainers/working-with-dev-containers.md @@ -5,51 +5,68 @@ visual representation of the running environment: ![Dev container integration in Coder dashboard](../../images/user-guides/devcontainers/devcontainer-agent-ports.png) +This page assumes you have a template with the [dev containers integration](./index.md) ready. + ## SSH Access -You can SSH into your dev container directly using the Coder CLI: +You can connect directly to your dev container. + +1. Run `coder config-ssh` to configure your SSH local client: + + ```shell + coder config-ssh + ``` + +1. SSH to your workspace: + + ```shell + ssh ..me.coder + ``` + + Example: + + ```shell + ssh devcontainer.myworkspace.me.coder + ``` -```console -coder ssh --container keen_dijkstra my-workspace +### Coder CLI + +```shell +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`. +Coder CLI connects to your dev container based on your workspace configuration. -## Web Terminal Access +### 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. +Once your workspace and dev container are running, you can use the **Terminal** +in the Coder workspace 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) -You can open your dev container directly in VS Code by: +To open your dev container directly in VS Code, select "Open in VS Code Desktop" from the Coder dashboard. -1. Selecting "Open in VS Code Desktop" from the Coder web interface -2. Using the Coder CLI with the container flag: +Alternatively, you can use the CLI: -```console -coder open vscode --container keen_dijkstra my-workspace +```shell +coder open vscode ``` -While optimized for VS Code, other IDEs with dev containers support may also -work. +Coder CLI connects to your dev container based on your workspace configuration. ## Port Forwarding -During the early access phase, port forwarding is limited to ports defined via -[`appPort`](https://containers.dev/implementors/json_reference/#image-specific) -in your `devcontainer.json` file. +Coder supports port forwarding for dev containers through the following mechanisms: + +1. **Defined Ports**: Ports defined in your `devcontainer.json` file via the [`appPort`](https://containers.dev/implementors/json_reference/#image-specific) property. + +1. **Dynamic Ports**: For ports not defined in your `devcontainer.json`, you can use the Coder CLI to forward them: -> [!NOTE] -> -> Support for automatic port forwarding via the `forwardPorts` property in -> `devcontainer.json` is planned for a future release. + ```shell + coder port-forward --tcp : + ``` For example, with this `devcontainer.json` configuration: @@ -59,25 +76,25 @@ For example, with this `devcontainer.json` configuration: } ``` -You can forward these ports to your local machine using: +You can access these ports directly through your browser via the Coder dashboard, or forward them to your local machine: -```console -coder port-forward my-workspace --tcp 8080,4000 +```shell +coder port-forward --tcp 8080,4000 ``` -This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port -4000 (local) -> 4000 (agent) -> 3000 (dev container). +This forwards port 8080 (local) → 8080 (container) and port 4000 (local) → 3000 (container). ## Dev Container Features -You can use standard dev container features in your `devcontainer.json` file. -Coder also maintains a -[repository of features](https://github.com/coder/devcontainer-features) to -enhance your development experience. +Dev container features allow you to enhance your development environment with pre-configured tooling. -Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server). +Coder supports the standard [dev container features specification](https://containers.dev/implementors/features/), allowing you to use any compatible features in your `devcontainer.json` file. -To use the code-server feature, add the following to your `devcontainer.json`: +### Example: Add code-server + +Coder maintains a [repository of features](https://github.com/coder/devcontainer-features) designed specifically for Coder environments. + +To add code-server (VS Code in the browser), add this to your `devcontainer.json`: ```json { @@ -91,7 +108,30 @@ To use the code-server feature, add the following to your `devcontainer.json`: } ``` -> [!NOTE] -> -> Remember to include the port in the `appPort` section to ensure proper port -> forwarding. +After rebuilding your container, code-server will be available on the configured port. + +### Using Multiple Features + +You can combine multiple features in a single `devcontainer.json`: + +```json +{ + "features": { + "ghcr.io/devcontainers/features/docker-in-docker:2": {}, + "ghcr.io/devcontainers/features/python:1": { + "version": "3.10" + }, + "ghcr.io/coder/devcontainer-features/code-server:1": { + "port": 13337 + } + } +} +``` + +## Rebuilding Dev Containers + +When you make changes to your `devcontainer.json` file, you need to rebuild the container for those changes to take effect. + +From the Coder dashboard, click the rebuild button on the dev container to apply your changes. + +You can also restart your workspace, which will rebuild containers when it restarts.