Skip to content

Commit 0ebab5c

Browse files
mafredrimafredri
committed
docs: restructure dev container documentation
Dev container admin docs were scattered across two locations: the Docker-based integration under extending-templates/ and Envbuilder under managing-templates/. There was no landing page explaining that two approaches exist or helping admins choose between them. This moves everything under admin/integrations/devcontainers/ with a decision guide at the top. Dev containers are an integration with the dev container specification, so integrations/ is a natural fit alongside JFrog, Vault, etc. Stub pages remain at the original locations for discoverability. New structure: admin/integrations/devcontainers/ ├── index.md # Landing page + decision guide ├── integration.md # Docker-based dev containers └── envbuilder/ ├── index.md ├── add-envbuilder.md ├── envbuilder-security-caching.md └── envbuilder-releases-known-issues.md Refs #21080
1 parent 25400fe commit 0ebab5c

File tree

17 files changed

+453
-432
lines changed

17 files changed

+453
-432
lines changed

‎docs/_redirects‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -5,9 +5,9 @@
55
/install/offline#offline-docs /install/airgap#airgap-docs 301
66
/install/offline#offline-container-images /install/airgap#airgap-container-images 301
77

8-
# Redirect old devcontainers folder to envbuilder
9-
/admin/templates/managing-templates/devcontainers /admin/templates/managing-templates/envbuilder 301
10-
/admin/templates/managing-templates/devcontainers/index /admin/templates/managing-templates/envbuilder 301
11-
/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/templates/managing-templates/envbuilder/add-envbuilder 301
12-
/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/templates/managing-templates/envbuilder/envbuilder-security-caching 301
13-
/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/templates/managing-templates/envbuilder/envbuilder-releases-known-issues 301
8+
# Redirect old devcontainers paths to new integrations location
9+
/admin/templates/managing-templates/devcontainers /admin/integrations/devcontainers/envbuilder 301
10+
/admin/templates/managing-templates/devcontainers/index /admin/integrations/devcontainers/envbuilder 301
11+
/admin/templates/managing-templates/devcontainers/add-devcontainer /admin/integrations/devcontainers/envbuilder/add-envbuilder 301
12+
/admin/templates/managing-templates/devcontainers/devcontainer-security-caching /admin/integrations/devcontainers/envbuilder/envbuilder-security-caching 301
13+
/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues /admin/integrations/devcontainers/envbuilder/envbuilder-releases-known-issues 301

‎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/extending-templates/devcontainers.md)
55+
[Development Container](./integrations/devcontainers/index.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/managing-templates/envbuilder/add-envbuilder.md renamed to docs/admin/integrations/devcontainers/envbuilder/add-envbuilder.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
A Coder administrator adds an Envbuilder-compatible template to Coder. This
44
allows the template to prompt the developer for their dev container repository's
5-
URL as a [parameter](../../extending-templates/parameters.md) when they create
5+
URL as a [parameter](../../../templates/extending-templates/parameters.md) when they create
66
their workspace. Envbuilder clones the repo and builds a container from the
77
`devcontainer.json` specified in the repo.
88

@@ -127,7 +127,7 @@ their development environments:
127127
| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
128128

129129
Your template can prompt the user for a repo URL with
130-
[parameters](../../extending-templates/parameters.md):
130+
[parameters](../../../templates/extending-templates/parameters.md):
131131

132132
![Dev container parameter screen](../../../../images/templates/devcontainers.png)
133133

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

File renamed without changes.

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

File renamed without changes.

‎docs/admin/integrations/devcontainers/envbuilder/index.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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 [Dev Containers integration](../integration.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+
> [Dev Containers integration](../integration.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.
16+
17+
Dev containers provide developers with increased autonomy and control over their
18+
Coder cloud development environments.
19+
20+
By using dev containers, developers can customize their workspaces with tools
21+
pre-approved by platform teams in registries like
22+
[JFrog Artifactory](../../jfrog-artifactory.md). This simplifies
23+
workflows, reduces the need for tickets and approvals, and promotes greater
24+
independence for developers.
25+
26+
## Prerequisites
27+
28+
An administrator should construct or choose a base image and create a template
29+
that includes a `devcontainer_builder` image before a developer team configures
30+
dev containers.
31+
32+
## Devcontainer Features
33+
34+
[Dev container Features](https://containers.dev/implementors/features/) allow
35+
owners of a project to specify self-contained units of code and runtime
36+
configuration that can be composed together on top of an existing base image.
37+
This is a good place to install project-specific tools, such as
38+
language-specific runtimes and compilers.
39+
40+
## Coder Envbuilder
41+
42+
[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
43+
maintained by Coder that runs dev containers via Coder templates and your
44+
underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
45+
46+
It is independently packaged and versioned from the centralized Coder
47+
open-source project. This means that Envbuilder can be used with Coder, but it
48+
is not required. It also means that dev container builds can scale independently
49+
of the Coder control plane and even run within a CI/CD pipeline.
50+
51+
## Next steps
52+
53+
- [Add an Envbuilder template](./add-envbuilder.md)

‎docs/admin/integrations/devcontainers/index.md‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
# Dev Containers
2+
3+
Dev containers allow developers to define their development environment
4+
as code using the [Dev Container specification](https://containers.dev/).
5+
Configuration lives in a `devcontainer.json` file alongside source code,
6+
enabling consistent, reproducible environments.
7+
8+
By adopting dev containers, organizations can:
9+
10+
- **Standardize environments**: Eliminate "works on my machine" issues while
11+
still allowing developers to customize their tools within approved boundaries.
12+
- **Scale efficiently**: Let developers maintain their own environment
13+
definitions, reducing the burden on platform teams.
14+
- **Improve security**: Use hardened base images and controlled package
15+
registries to enforce security policies while enabling developer self-service.
16+
17+
Coder supports two approaches for running dev containers. Choose based on your
18+
infrastructure and workflow requirements.
19+
20+
## Dev Containers Integration
21+
22+
The Dev Containers Integration uses the standard `@devcontainers/cli` and Docker
23+
to run containers inside your workspace. This is the recommended approach for
24+
most use cases.
25+
26+
**Best for:**
27+
28+
- Workspaces with Docker available (Docker-in-Docker or mounted socket)
29+
- Container management in the Coder dashboard (discovery, status, rebuild)
30+
- Multi-container development with Docker Compose
31+
32+
[Configure Dev Containers Integration](./integration.md)
33+
34+
For user documentation, see
35+
[Working with Dev Containers](../../../user-guides/devcontainers/index.md).
36+
37+
## Envbuilder
38+
39+
Envbuilder transforms the workspace image itself from a `devcontainer.json`,
40+
rather than running containers inside the workspace. It does not require
41+
a Docker daemon.
42+
43+
**Best for:**
44+
45+
- Environments where Docker is unavailable or restricted
46+
- Infrastructure-level control over image builds, caching, and security scanning
47+
- Kubernetes-native deployments without privileged containers
48+
49+
[Configure Envbuilder](./envbuilder/index.md)

0 commit comments

Comments
 (0)