8000 add comparison doc; crosslink · coder/coder@2fe5291 · GitHub
[go: up one dir, main page]
Skip to content

Commit 2fe5291

Browse files
EdwardAngertEdwardAngert
committed
add comparison doc; crosslink
1 parent 8f392c0 commit 2fe5291

File tree

4 files changed

+85
-4
lines changed

4 files changed

+85
-4
lines changed

‎docs/admin/templates/extending-templates/dev-containers-envbuilder.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Choose an approach to Dev Containers in Coder
2+
3+
Coder supports two independent ways to run Dev Containers inside a workspace.
4+
5+
Both implement the [Dev Container specification](https://containers.dev/), but they differ in how the container is built,
6+
who controls it, and which runtime requirements exist.
7+
8+
Use this page to decide which path fits your project or platform needs.
9+
10+
## Options at a glance
11+
12+
| Capability / Trait | Dev Containers integration (CLI-based) | Envbuilder Dev Containers |
13+
|------------------------------------------|------------------------------------------|-------------------------------------------|
14+
| Build engine | `@devcontainers/cli` + Docker | Envbuilder transforms the workspace image |
15+
| Runs separate Docker container | Yes (parent workspace + child container) | No (modifies the parent container) |
16+
| Multiple Dev Containers per workspace | Yes | No |
17+
| Rebuild when `devcontainer.json` changes | Yes (auto-prompt) | Limited (requires full workspace rebuild) |
18+
| Docker required in workspace | Yes | No (works in restricted envs) |
19+
| Admin vs. developer control | Developer decides per repo | Platform admin manages via template |
20+
| Templates | Standard `devcontainer.json` | Terraform + Envbuilder blocks |
21+
| Suitable for CI / AI agents | Yes. Deterministic, composable | Less ideal. No isolated container |
22+
23+
## When to choose the Dev Containers integration
24+
25+
Choose the new integration if:
26+
27+
- Your workspace image can run Docker (DinD, Sysbox, or a mounted Docker socket).
28+
- You need multiple Dev Containers (like `frontend`, `backend`, `db`) in a single workspace.
29+
- Developers should own their environment and rebuild on demand.
30+
- You rely on features such as automatic port forwarding, full SSH into containers, or change-detection prompts.
31+
32+
[Dev Container integration](./devcontainers.md) documentation.
33+
34+
## When to choose Envbuilder
35+
36+
Envbuilder remains a solid choice when:
37+
38+
- Docker isn’t available or allowed inside the workspace image.
39+
- The platform team wants tight control over container contents via Terraform.
40+
- A single layered environment is sufficient (no need for separate sub-containers).
41+
- You already have Envbuilder templates in production and they meet current needs.
42+
43+
[Envbuilder Dev Container](../managing-templates/devcontainers/add-devcontainer.md#envbuilder-terraform-provider) documentation.
44+
45+
## How to migrate from Envbuilder to the Dev Containers integration
46+
47+
1. Ensure the workspace image can run Docker and has sufficient resources:
48+
49+
```shell
50+
docker ps
51+
```
52+
53+
1. Remove any Envbuilder blocks that reference `coder_dev_envbuilder` from the template.
54+
1. Add (or keep) a standard `.devcontainer/` folder with `devcontainer.json` in the repository.
55+
1. Add the `devcontainers-cli` module:
56+
57+
```terraform
58+
module "devcontainers_cli" {
59+
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
60+
agent_id = coder_agent.main.id
61+
}
62+
```
63+
64+
1. Start a new workspace.
65+
Coder detects and launches the dev container automatically.
66+
1. Verify ports, SSH, and rebuild prompts function as expected.
67+
68+
## Related reading
69+
70+
- [Dev Containers Integration](./index.md)
71+
- [Troubleshooting Dev Containers](./troubleshooting-dev-containers.md)
72+
- [Envbuilder documentation](https://github.com/coder/envbuilder)
73+
- [Dev Container specification](https://containers.dev/)

‎docs/admin/templates/extending-templates/devcontainers.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,9 @@ When integrated with Coder templates, they provide:
1717
- **Consistency across teams**: Everyone works in identical environments regardless of their local machine.
1818
- **Version control**: Development environment changes are tracked alongside code changes.
1919

20+
Visit [Choose an approach to Dev Containers in Coder](./dev-containers-envbuilder.md) for an in-depth comparison between
21+
the Dev Container integration and the legacy Envbuilder integration.
22+
2023
## Prerequisites
2124

2225
- Dev containers require Docker to build and run containers inside the workspace.

‎docs/manifest.json

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -602,13 +602,18 @@
602602
},
603603
{
604604
"title": "Configure a template for dev containers",
605-
"description": "How to use configure your template for dev containers",
605+
"description": "How to configure your template for dev containers",
606606
"path": "./admin/templates/extending-templates/devcontainers.md",
607607
"children": [
608608
{
609609
"title": "Advanced dev container configurations",
610610
"description": "Enhance your dev container configurations with multiple containers, repo selection, monitoring, and more.",
611611
"path": "./admin/templates/extending-templates/advanced-dev-containers.md"
612+
},
613+
{
614+
"title": "Choose an approach to Dev Containers in Coder",
615+
"description": "How to choose the right Dev Container integration.",
616+
"path": "./admin/templates/extending-templates/dev-containers-envbuilder.md"
612617
}
613618
]
614619
},

‎docs/user-guides/devcontainers/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -72,8 +72,8 @@ Add the file name to your project's `.gitignore` or to your
7272
| Requirements | Docker access in workspace | Compatible with more restricted environments |
7373

7474
Choose the appropriate solution based on your team's needs and infrastructure constraints.
75-
For additional details on Envbuilder's dev container support, see the
76-
[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
75+
76+
Visit [Choose an approach to Dev Containers in Coder](../../admin/templates/extending-templates/dev-containers-envbuilder.md) for a more in-depth comparison.
7777

7878
## Known Limitations
7979

@@ -83,5 +83,5 @@ If your template allows for prebuilt workspaces, do not select a prebuilt worksp
8383

8484
## Next Steps
8585

86-
- [Dev container specification](https://containers.dev/)
86+
- [Dev Container specification](https://containers.dev/)
8787
- [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)

0 commit comments

Comments
 (0)
0