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. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy