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..269dd3477aa58 --- /dev/null +++ b/docs/admin/templates/extending-templates/advanced-dev-containers.md @@ -0,0 +1,110 @@ +# Advanced Dev Container Configuration + +This page extends the [devcontainers 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: `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" + base_dir = "/home/coder/frontend" +} + +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" + base_dir = "/home/coder/backend" +} + +# Dev container resources +resource "coder_devcontainer" "frontend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/frontend/${module.git-clone-frontend[0].folder_name}" +} + +resource "coder_devcontainer" "backend" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/backend/${module.git-clone-backend[0].folder_name}" +} +``` + +Each dev container appears as a separate agent, so developers can connect to any +component in the workspace. + +## 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" "enable_frontend" { + type = "bool" + name = "Enable frontend container" + default = true + mutable = true + order = 3 +} + +resource "coder_devcontainer" "frontend" { + count = data.coder_parameter.enable_frontend.value ? data.coder_workspace.me.start_count : 0 + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/frontend/${module.git-clone-frontend[0].folder_name}" +} +``` + +## 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 = "Dev Container template" + value = "https://github.com/devcontainers/template-starter.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 + base_dir = "/home/coder" + } + ``` + +## Troubleshooting + +1. Run `docker ps` inside the workspace to ensure Docker is available. +1. Check `/tmp/coder-agent.log` for agent logs. +1. Verify that the workspace image includes Node/npm. 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..898f0d8d4975b --- /dev/null +++ b/docs/admin/templates/extending-templates/dev-containers-envbuilder.md @@ -0,0 +1,57 @@ +# 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 (CLI-based) | Envbuilder Dev Containers | +|------------------------------------------|------------------------------------------|-------------------------------------------| +| Build engine | `@devcontainers/cli` + Docker | Envbuilder transforms the workspace image | +| Runs separate Docker container | Yes (parent workspace + child container) | No (modifies the parent container) | +| Multiple Dev Containers per workspace | Yes | No | +| Rebuild when `devcontainer.json` changes | Yes (auto-prompt) | Limited (requires full workspace rebuild) | +| Docker required in workspace | Yes | No (works in restricted envs) | +| Templates | Standard `devcontainer.json` | Terraform + Envbuilder blocks | +| Suitable for CI / AI agents | Yes. Deterministic, composable | Less ideal. No isolated container | + +## How To Migrate From Envbuilder to the Dev Containers Integration + +1. Ensure the workspace image can run Docker and has sufficient resources: + + ```shell + docker ps + ``` + +1. Remove any Envbuilder blocks that reference `coder_dev_envbuilder` from the template. +1. Add (or keep) a standard `.devcontainer/` folder with `devcontainer.json` in the repository. +1. Follow the [dev containers documentation](./devcontainers.md) for the full list of steps and options. + + At minimum, add the `devcontainers-cli` module and `coder_devcontainer` resource: + + ```terraform + module "devcontainers_cli" { + source = "dev.registry.coder.com/modules/devcontainers-cli/coder" + agent_id = coder_agent.main.id + } + resource "coder_devcontainer" "project" { # `project` in this example is how users will connect to the dev container: `ssh://project..me.coder` + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/project" + } + ``` + +1. Start a new workspace. + Coder detects and launches the dev container automatically. +1. Verify ports, SSH, and rebuild prompts function as expected. + +## Related Reading + +- [Dev Containers Integration](./index.md) +- [Troubleshooting Dev Containers](../../../user-guides/devcontainers/troubleshooting-dev-containers.md) +- [Envbuilder on GitHub](https://github.com/coder/envbuilder) +- [Dev Container specification](https://containers.dev/) diff --git a/docs/admin/templates/extending-templates/devcontainers.md b/docs/admin/templates/extending-templates/devcontainers.md index d4284bf48efde..b5735e29ecc35 100644 --- a/docs/admin/templates/extending-templates/devcontainers.md +++ b/docs/admin/templates/extending-templates/devcontainers.md @@ -1,79 +1,153 @@ -# 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 a consistent, reproducible development environment 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 control**: Development environment changes are tracked alongside code changes. + +Visit [Choose an approach to Dev Containers](./dev-containers-envbuilder.md) for an in-depth comparison between +the Dev Container integration and the legacy Envbuilder integration. + +## 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. + + To confirm that Docker is configured correctly, create a test workspace and confirm that `docker ps` runs. + 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 + 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: + +```shell +RUN npm install -g @devcontainers/cli +``` -## Configure Automatic Dev Container Startup +## 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 [`git-clone`](#clone-the-repository), point the resource at the folder that contains `devcontainer.json`: ```terraform -resource "coder_devcontainer" "my-repository" { +resource "coder_devcontainer" "project" { # `project` in this example is how users will connect to the dev container: `ssh://project..me.coder` 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" } ``` -> [!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. +## Clone the Repository - +This step is optional, but it ensures that the project is present before the dev container starts. -> [!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. +Note that if you use the `git-clone` module, update or replace the `coder_devcontainer` resource +to point to `/home/coder/project/${module.git-clone[0].folder_name}` so that it is only defined once: -## Enable Dev Containers Integration +```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 = "https://github.com/example/project.git" + base_dir = "/home/coder" +} -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: +resource "coder_devcontainer" "project" { + count = data.coder_workspace.me.start_count + agent_id = coder_agent.main.id + workspace_folder = "/home/coder/${module.git-clone[0].folder_name}" +} +``` -```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. +## Dev Container Features + +Enhance your dev container experience with additional features. +For more advanced use cases, consult the [advanced dev containers doc](./advanced-dev-containers.md). + +### Custom applications + +```jsonc +{ + "customizations": { + "coder": { + "apps": [ + { + "slug": "flask-app", + "command": "python app.py", + "icon": "/icon/flask.svg", + "subdomain": true, + "healthcheck": { + "url": "http://localhost:5000/health", + "interval": 10, + "threshold": 10 + } + } + ] + } + } } ``` -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: -## Complete Template Example +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. -Here's a simplified template example that enables the dev containers -integration: + 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 +157,80 @@ 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 + agent_id = coder_agent.main.id } -resource "coder_devcontainer" "my-repository" { +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 = "https://github.com/coder/coder.git" + base_dir = "/home/coder" +} + +resource "coder_devcontainer" "project" { 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/${module.git-clone[0].folder_name}" } 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}", + "CODER_AGENT_DEVCONTAINERS_ENABLE=true" ] - # ... 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. + +### Dev container does not start + +1. Docker daemon not running inside the workspace. +1. `devcontainer.json` missing or is in the wrong place. +1. Build errors: check agent logs. + +### Permission errors + +- Docker socket not mounted or user lacks access. +- Workspace not `privileged` and no rootless runtime. + +### Slow builds + +- Allocate more CPU/RAM. +- Use image caching or pre-build common images. + ## 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/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md index 5d2ac0a07f9e2..85e5906d8152a 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/dev-containers-envbuilder.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..4737ef2a30614 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 @@ -117,6 +44,7 @@ open-source project. This means that Envbuilder can be used with Coder, but it is not required. It also means that dev container builds can scale independently of the Coder control plane and even run within a CI/CD pipeline. -## Next steps +## 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/images/screenshots/workspace-running-with-topbar.png b/docs/images/screenshots/workspace-running-with-topbar.png index ab3f6a78a9e6e..0af0b6527e758 100644 Binary files a/docs/images/screenshots/workspace-running-with-topbar.png and b/docs/images/screenshots/workspace-running-with-topbar.png differ 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..e6bc7ad95d8c8 100644 --- a/docs/user-guides/devcontainers/index.md +++ b/docs/user-guides/devcontainers/index.md @@ -1,27 +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 the [`@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 - Appropriate permissions to execute Docker commands inside your workspace @@ -38,62 +25,32 @@ 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 builds (or rebuilds) and starts the dev container based on the configuration. 1. Your workspace automatically detects the running dev container. +1. If the configuration changes, the workspace prompts you to rebuild the dev container. ## Features -### Available Now +### Detection & 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 discovery of `.devcontainer` configs. +- 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 (`coder ssh ..me.coder`). +- Automatic port forwarding. -## Limitations during Early Access +## Known Limitations -During the early access phase, the dev containers integration has the following -limitations: +Currently, dev containers are not compatible with [prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md). -- 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 - -These limitations will be addressed in future updates as the feature matures. - -## Comparison with Envbuilder-based Dev Containers - -| 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 | - -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..8e9b869330d4e 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,16 @@ 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. + +## Rebuild prompt does not appear + +1. Confirm that you saved `devcontainer.json` in the correct repo path detected by Coder. +1. Check agent logs for `devcontainer build` errors. + +## 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..1377b6a0757d8 100644 --- a/docs/user-guides/devcontainers/working-with-dev-containers.md +++ b/docs/user-guides/devcontainers/working-with-dev-containers.md @@ -5,19 +5,26 @@ 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 [dev containers integration](./index.md) ready. + ## SSH Access You can SSH into your dev container directly using the Coder CLI: ```console -coder ssh --container keen_dijkstra my-workspace +coder ssh --container my-container-name my-workspace ``` +Remember to replace: + +- `my-container-name` with the dev container agent name. +- `my-workspace` with your workspace's name. + > [!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`. +> Starting with Coder v2.24.0, `coder config-ssh` works with dev containers. +> If you’re using an older Coder version, add `--container ` to the +> `ProxyCommand` entry in your SSH config. ## Web Terminal Access @@ -34,7 +41,7 @@ You can open your dev container directly in VS Code by: 2. Using the Coder CLI with the container flag: ```console -coder open vscode --container keen_dijkstra my-workspace +coder open vscode --container my-container-name my-workspace ``` While optimized for VS Code, other IDEs with dev containers support may also @@ -42,31 +49,14 @@ work. ## 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. - -> [!NOTE] -> -> Support for automatic port forwarding via the `forwardPorts` property in -> `devcontainer.json` is planned for a future release. - -For example, with this `devcontainer.json` configuration: - -```json -{ - "appPort": ["8080:8080", "4000:3000"] -} -``` - -You can forward these ports to your local machine using: +Coder automatically forwards any port declared in `appPort` or `forwardPorts`. +Use the dashboard to open a forwarded port, or the CLI: ```console coder port-forward my-workspace --tcp 8080,4000 ``` -This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port -4000 (local) -> 4000 (agent) -> 3000 (dev container). +If you need a port that isn’t declared, pass it explicitly to `coder port-forward`. ## Dev Container Features 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