Skip to content

Commit 69f5b4a

Browse files
mafredrimafredri
committed
docs: update dev containers documentation for GA
PR #18907 attempted to update the dev containers docs but was closed due to inaccuracies from limited implementation knowledge. The main issues were: - SSH examples used the deprecated --container flag instead of the agent-based access pattern (coder ssh workspace.agent) - Port forwarding focused on appPort when native forwarding to sub-agents is the primary method - Prerequisites implied users needed to "enable" Dev Containers when it's on by default—the real requirements are Docker and the CLI - The "automatic build" section was misleading since autostart is off by default (discovery is on, but containers don't auto-start) The Envbuilder docs were in a folder called "devcontainers" which caused confusion about which approach was primary. Renamed to "envbuilder" and added notes recommending native Dev Containers for most use cases. Also fixes registry URLs that pointed to dev.registry instead of registry.coder.com. Refs #18907
1 parent d5bb136 commit 69f5b4a

File tree

15 files changed

+379
-151
lines changed

15 files changed

+379
-151
lines changed

‎.markdownlint-cli2.jsonc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"ignores": ["PLAN.md"],
3+
}

‎docs/admin/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ For any information not strictly contained in these sections, check out our
5252
### Development containers (dev containers)
5353

5454
- A
55-
[Development Container](./templates/managing-templates/devcontainers/index.md)
55+
[Development Container](./templates/extending-templates/devcontainers.md)
5656
is an open-source specification for defining development environments (called
5757
dev containers). It is generally stored in VCS alongside associated source
5858
code. It can reference an existing base image, or a custom Dockerfile that

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ to ensure the `@devcontainers/cli` is installed in your workspace:
3636
```terraform
3737
module "devcontainers-cli" {
3838
count = data.coder_workspace.me.start_count
39-
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
39+
source = "registry.coder.com/coder/devcontainers-cli/coder"
4040
agent_id = coder_agent.dev.id
4141
}
4242
```
@@ -232,7 +232,7 @@ resource "coder_agent" "dev" {
232232
233233
module "devcontainers-cli" {
234234
count = data.coder_workspace.me.start_count
235-
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
235+
source = "registry.coder.com/coder/devcontainers-cli/coder"
236236
agent_id = coder_agent.dev.id
237237
}
238238

‎docs/admin/templates/index.md‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,10 @@ needs of different teams.
4848

4949
- [Image management](./managing-templates/image-management.md): Learn how to
5050
create and publish images for use within Coder workspaces & templates.
51-
- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
52-
dev containers to allow teams to bring their own tools into Coder workspaces.
53-
- [Early Access Dev Containers](../../user-guides/devcontainers/index.md): Try our
54-
new direct devcontainers integration (distinct from Envbuilder-based
55-
approach).
51+
- [Dev Containers integration](./extending-templates/devcontainers.md): Enable
52+
native dev containers support using `@devcontainers/cli` and Docker.
53+
- [Envbuilder](./managing-templates/envbuilder/index.md): Alternative approach
54+
for environments without Docker access.
5655
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
5756
Configure your template to prevent certain resources from being destroyed
5857
(e.g. user disks).

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md renamed to docs/admin/templates/managing-templates/envbuilder/add-devcontainer.md

File renamed without changes.

docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md renamed to docs/admin/templates/managing-templates/envbuilder/devcontainer-releases-known-issues.md

File renamed without changes.

docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md renamed to docs/admin/templates/managing-templates/envbuilder/devcontainer-security-caching.md

File renamed without changes.

docs/admin/templates/managing-templates/devcontainers/index.md renamed to docs/admin/templates/managing-templates/envbuilder/index.md

Lines changed: 28 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,18 @@
1-
# Dev containers
2-
3-
A Development Container is an
4-
[open-source specification](https://containers.dev/implementors/spec/) for
5-
defining containerized development environments which are also called
6-
development containers (dev containers).
1+
# Envbuilder
2+
3+
Envbuilder is an open-source tool that builds development environments from
4+
[dev container](https://containers.dev/implementors/spec/) configuration files.
5+
Unlike the [native Dev Containers integration](../extending-templates/devcontainers.md),
6+
Envbuilder transforms the workspace image itself rather than running containers
7+
inside the workspace.
8+
9+
> [!NOTE]
10+
>
11+
> For most use cases, we recommend the
12+
> [native Dev Containers integration](../extending-templates/devcontainers.md),
13+
> which uses the standard `@devcontainers/cli` and Docker. Envbuilder is an
14+
> alternative for environments where Docker is not available or for
15+
> administrator-controlled dev container workflows.
716
817
Dev containers provide developers with increased autonomy and control over their
918
Coder cloud development environments.
@@ -117,6 +126,19 @@ open-source project. This means that Envbuilder can be used with Coder, but it
117126
is not required. It also means that dev container builds can scale independently
118127
of the Coder control plane and even run within a CI/CD pipeline.
119128

129+
## Alternative: Native Dev Containers integration
130+
131+
For most use cases, we recommend the
132+
[native Dev Containers integration](../extending-templates/devcontainers.md),
133+
which uses the standard `@devcontainers/cli` and Docker. This approach:
134+
135+
- Supports multiple dev containers per workspace
136+
- Enables user-controlled dev container management
137+
- Allows on-demand container rebuilds without restarting the workspace
138+
139+
See the [Dev Containers integration user guide](../../../../user-guides/devcontainers/index.md)
140+
for more information.
141+
120142
## Next steps
121143

122144
- [Add a dev container template](./add-devcontainer.md)

‎docs/admin/templates/managing-templates/image-management.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,4 +70,5 @@ specific tooling for their projects. The [Dev Container](https://containers.dev)
7070
specification allows developers to define their projects dependencies within a
7171
`devcontainer.json` in their Git repository.
7272

73-
- [Learn how to integrate Dev Containers with Coder](./devcontainers/index.md)
73+
- [Configure a template for Dev Containers](../extending-templates/devcontainers.md) (recommended)
74+
- [Learn about Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)

‎docs/admin/templates/managing-templates/index.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,5 +96,6 @@ coder templates delete <template-name>
9696
## Next steps
9797

9898
- [Image management](./image-management.md)
99-
- [Devcontainer templates](./devcontainers/index.md)
99+
- [Dev Containers integration](../extending-templates/devcontainers.md) (recommended)
100+
- [Envbuilder](./envbuilder/index.md) (alternative for environments without Docker)
100101
- [Change management](./change-management.md)

0 commit comments

Comments
 (0)