- Notifications
You must be signed in to change notification settings - Fork928
docs: add comprehensive dev containers documentation with examples#18582
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Draft
EdwardAngert wants to merge25 commits intomainChoose a base branch
base:main
Could not load branches
Branch not found:{{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline, and old review comments may become outdated.
+719 −256
Draft
Changes fromall commits
Commits
Show all changes
25 commits Select commitHold shift + click to select a range
718e6f9 remove ea feature status
EdwardAngertba7a36c add advanced dev container doc
EdwardAngertef8a4ea update devcontainers
EdwardAngertf4db3da new workspace screenshot
EdwardAngertdf07196 consistent and working examples
EdwardAngert18998b7 edits; prep advanced doc
EdwardAngertddc5893 Merge branch 'main' into dev-container-ga
EdwardAngert048cf5b advanced features
EdwardAngert5dc41a5 better examples
EdwardAngertbe23e85 init user-facing update
EdwardAngertec77a25 remove coder_agent_devcontainers_enable requirement
EdwardAngert06d714c update features; add personal devcontainer file
EdwardAngert8f392c0 update troubleshooting
EdwardAngert2fe5291 add comparison doc; crosslink
EdwardAngert33d3eed shorten title
EdwardAngert747822e clarify envbuilder doc titles
EdwardAngertd9f818c update envbuilder doc with dev container integration consideration
EdwardAngertc10eb7e update envbuilder add-devcontainer with dev container integration links
EdwardAngert3f8970e envbuilder tweaks
EdwardAngert0d0a9ba link fix
EdwardAngert88e7c0f tweak to devcontainer.local note
EdwardAngert8f5e613 ap title case
EdwardAngerte83d564 leftover ea language
EdwardAngert03c60bf update ssh note and example
EdwardAngertcfcef3c update example template
EdwardAngertFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
222 changes: 222 additions & 0 deletionsdocs/admin/templates/extending-templates/advanced-dev-containers.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,222 @@ | ||
| # Advanced Dev Container Configuration | ||
| This page extends [devcontainers.md](./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 three: `frontend`, `backend`, and a `database`: | ||
| ```terraform | ||
| # Clone each repo | ||
| module "git_clone_frontend" { | ||
| count = data.coder_workspace.me.start_count | ||
| source = "registry.coder.com/modules/git-clone/coder" | ||
| version = "~> 1.0" | ||
| 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 = "registry.coder.com/modules/git-clone/coder" | ||
| version = "~> 1.0" | ||
| agent_id = coder_agent.main.id | ||
| url = "https://github.com/your-org/backend.git" | ||
| base_dir = "/home/coder/backend" | ||
| } | ||
| module "git_clone_database" { | ||
| count = data.coder_workspace.me.start_count | ||
| source = "registry.coder.com/modules/git-clone/coder" | ||
| version = "~> 1.0" | ||
| agent_id = coder_agent.main.id | ||
| url = "https://github.com/your-org/database.git" | ||
| base_dir = "/home/coder/database" | ||
| } | ||
| # 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}" | ||
| depends_on = [module.git_clone_frontend] | ||
| } | ||
| 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}" | ||
| depends_on = [module.git_clone_backend] | ||
| } | ||
| resource "coder_devcontainer" "database" { | ||
| count = data.coder_workspace.me.start_count | ||
| agent_id = coder_agent.main.id | ||
| workspace_folder = "/home/coder/database/${module.git_clone_database[0].folder_name}" | ||
| depends_on = [module.git_clone_database] | ||
| } | ||
| ``` | ||
| Each dev container appears as a separate agent, so developers can connect to any | ||
| component in the workspace. | ||
| ## Personal Overrides | ||
| Let developers extend the repo’s `devcontainer.json` with an ignored (by Git) `devcontainer.local.json` file | ||
| so they can add personal tools without changing the canonical configuration: | ||
| ```jsonc | ||
| { | ||
| "extends": "./devcontainer.json", | ||
| "features": { | ||
| "ghcr.io/devcontainers/features/node": { "version": "20" } | ||
| }, | ||
| "postStartCommand": "npm i -g tldr" | ||
| } | ||
| ``` | ||
| Add the file name to your project's `.gitignore` or the user's | ||
| [global exclude file](https://docs.github.com/en/get-started/git-basics/ignoring-files#configuring-ignored-files-for-all-repositories-on-your-computer). | ||
| ## 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}" | ||
| depends_on = [module.git_clone_frontend] | ||
| } | ||
| ``` | ||
| ## 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: | ||
| ### Dropdown selector | ||
| ```terraform | ||
| data "coder_parameter" "project" { | ||
| name = "Project" | ||
| description = "Choose a project" | ||
| type = "string" | ||
| mutable = true | ||
| order = 1 | ||
| option { name = "E-commerce FE" value = "https://github.com/org/ecom-fe.git" icon = "/icon/react.svg" } | ||
| option { name = "Payment API" value = "https://github.com/org/pay.git" icon = "/icon/nodejs.svg" } | ||
| } | ||
| module "git_clone_selected" { | ||
| count = data.coder_workspace.me.start_count | ||
| source = "registry.coder.com/modules/git-clone/coder" | ||
| version = "~> 1.0" | ||
| agent_id = coder_agent.main.id | ||
| url = data.coder_parameter.project.value | ||
| base_dir = "/home/coder/project" | ||
| } | ||
| ``` | ||
| ### Team-based selection | ||
| ```terraform | ||
| data "coder_parameter" "team" { | ||
| name = "Team" | ||
| type = "string" | ||
| mutable = true | ||
| order = 1 | ||
| option { name = "Frontend" value = "frontend" icon = "/icon/react.svg" } | ||
| option { name = "Backend" value = "backend" icon = "/icon/nodejs.svg" } | ||
| } | ||
| locals { | ||
| repos = { | ||
| frontend = ["https://github.com/your-org/web.git"] | ||
| backend = ["https://github.com/your-org/api.git"] | ||
| } | ||
| } | ||
| module "git_clone_team" { | ||
| count = length(local.repos[data.coder_parameter.team.value]) * data.coder_workspace.me.start_count | ||
| source = "registry.coder.com/modules/git-clone/coder" | ||
| version = "~> 1.0" | ||
| agent_id = coder_agent.main.id | ||
| url = local.repos[data.coder_parameter.team.value][count.index] | ||
| base_dir = "/home/coder/${replace(basename(url), \".git\", \"\")}" | ||
| } | ||
| ``` | ||
| ## Infrastructure Tuning | ||
| Adjust workspace infrastructure to set memory/CPU limits, attach a custom Docker network, | ||
| or add persistent volumes—to improve performance and isolation for dev containers: | ||
| ### Resource limits | ||
| ```terraform | ||
| resource "docker_container" "workspace" { | ||
| count = data.coder_workspace.me.start_count | ||
| image = "codercom/enterprise-node:ubuntu" | ||
| resources { | ||
| memory = 4096 # MiB | ||
| cpus = 2 | ||
| memory_swap = 8192 | ||
| } | ||
| } | ||
| ``` | ||
| ### Custom network | ||
| ```terraform | ||
| resource "docker_network" "dev" { | ||
| name = "coder-${data.coder_workspace.me.id}-dev" | ||
| } | ||
| resource "docker_container" "workspace" { | ||
| networks_advanced { name = docker_network.dev.name } | ||
| } | ||
| ``` | ||
| ### Volume caching | ||
| ```terraform | ||
| resource "docker_volume" "node_modules" { | ||
| name = "coder-${data.coder_workspace.me.id}-node-modules" | ||
| lifecycle { ignore_changes = all } | ||
| } | ||
| resource "docker_container" "workspace" { | ||
| volumes { | ||
| container_path = "/home/coder/project/node_modules" | ||
| volume_name = docker_volume.node_modules.name | ||
| } | ||
| } | ||
| ``` | ||
| ## Troubleshooting | ||
| 1. Run `docker ps` inside the workspace to ensure Docker is available. | ||
| 1. Check `/tmp/startup.log` for agent logs. | ||
| 1. Verify the workspace image includes Node/npm or add the `nodejs` module before the `devcontainers_cli` module. |
73 changes: 73 additions & 0 deletionsdocs/admin/templates/extending-templates/dev-containers-envbuilder.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,73 @@ | ||
| # 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) | | ||
| | Admin vs. developer control | Developer decides per repo | Platform admin manages via template | | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others.Learn more. This is incorrect. both can be determined via parameters | ||
| | Templates | Standard `devcontainer.json` | Terraform + Envbuilder blocks | | ||
| | Suitable for CI / AI agents | Yes. Deterministic, composable | Less ideal. No isolated container | | ||
| ## When To Choose the Dev Containers Integration | ||
| Choose the new integration if: | ||
| - Your workspace image can run Docker (DinD, Sysbox, or a mounted Docker socket). | ||
| - You need multiple Dev Containers (like `frontend`, `backend`, `db`) in a single workspace. | ||
| - Developers should own their environment and rebuild on demand. | ||
| - You rely on features such as automatic port forwarding, full SSH into containers, or change-detection prompts. | ||
| [Dev Container integration](./devcontainers.md) documentation. | ||
| ## When To Choose Envbuilder | ||
| Envbuilder remains a solid choice when: | ||
| - Docker isn’t available or allowed inside the workspace image. | ||
| - The platform team wants tight control over container contents via Terraform. | ||
| - A single layered environment is sufficient (no need for separate sub-containers). | ||
| - You already have Envbuilder templates in production and they meet current needs. | ||
| [Envbuilder Dev Container](../managing-templates/devcontainers/add-devcontainer.md#envbuilder-terraform-provider) documentation. | ||
| ## 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. Add the `devcontainers-cli` module: | ||
| ```terraform | ||
| module "devcontainers_cli" { | ||
| source = "dev.registry.coder.com/modules/devcontainers-cli/coder" | ||
| agent_id = coder_agent.main.id | ||
| } | ||
| ``` | ||
| 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/) | ||
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.