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..6cba8db818354 --- /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 = "dev.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 = "dev.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 = "dev.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..83cc80537c0f2 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -1,79 +1,191 @@ -# 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 enable dev containers in workspaces, [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. +- **Zero setup time**: 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 + 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, install `@devcontainer/cli` manually in your base image: -## Configure Automatic Dev Container Startup +```shell +RUN npm install -g @devcontainers/cli +``` + +## Define the Dev Container Resource -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: +If you don't use the [`git-clone`](#clone-the-repository) module, point the resource at the folder that contains `devcontainer.json`: ```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" + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/project" # or /home/coder/project/.devcontainer } ``` > [!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. - +## Add Dev Container Features -> [!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. +Enhance your dev container experience with additional features. +For more advanced use cases, consult the [advanced dev containers doc](./advanced-dev-containers.md). -## Enable Dev Containers Integration +### Custom applications -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: +Add apps to the dev container workspace resource for one-click access. ```terraform -resource "docker_container" "workspace" { - count = data.coder_workspace.me.start_count - image = "codercom/oss-dogfood:latest" - env = [ - "CODER_AGENT_DEVCONTAINERS_ENABLE=true", - # ... Other environment variables. - ] - # ... Other container configuration. + "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 + }, + } + ] + } + }, } ``` -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. +
-## Complete Template Example +### Agent naming -Here's a simplified template example that enables the dev containers -integration: +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`. + +### 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 { @@ -83,44 +195,73 @@ terraform { } } -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 + 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 = "/home/coder" } resource "coder_devcontainer" "my-repository" { count = data.coder_workspace.me.start_count - agent_id = coder_agent.dev.id - workspace_folder = "/home/coder/my-repository" + 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. - ] - # ... Other container configuration. + "CODER_AGENT_TOKEN=${coder_agent.main.token}", + "CODER_AGENT_URL=${data.coder_workspace.me.access_url}" + ] } ``` +## 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..7669b1aa19b58 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,36 @@ 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 - -- 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 - -### Coming Soon +### Detection and Lifecycle -- Dev container change detection -- On-demand dev container recreation -- Support for automatic port forwarding inside the container -- Full native SSH support to dev containers +- Automatic dev container detection from repositories. +- Change detection with rebuild prompts. +- Rebuild containers with one click from the Coder dashboard. -## Limitations during Early Access +### Connectivity -During the early access phase, the dev containers integration has the following -limitations: +- Full SSH access directly into dev containers -- 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 ..me.coder + ``` -These limitations will be addressed in future updates as the feature matures. +- Automatic port forwarding. -## 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..bc145797316ec 100644 --- a/docs/user-guides/devcontainers/working-with-dev-containers.md +++ b/docs/user-guides/devcontainers/working-with-dev-containers.md @@ -5,6 +5,8 @@ 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: 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