Skip to content

Commit 0e8383e

Browse files
EdwardAngertEdwardAngert
committed
update user-guide
1 parent 0f47c56 commit 0e8383e

File tree

1 file changed

+21
-64
lines changed

1 file changed

+21
-64
lines changed

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

Lines changed: 21 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,14 @@
11
# Dev Containers Integration
22

3-
> [!NOTE]
4-
>
5-
> The Coder dev containers integration is an [early access](../../install/releases/feature-stages.md) feature.
6-
>
7-
> While functional for testing and feedback, it may change significantly before general availability.
8-
9-
The dev containers integration is an early access feature that enables seamless
10-
creation and management of dev containers in Coder workspaces. This feature
11-
leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and
12-
[Docker](https://www.docker.com) to provide a streamlined development
13-
experience.
14-
15-
This implementation is different from the existing
16-
[Envbuilder-based dev containers](../../admin/templates/managing-templates/devcontainers/index.md)
17-
offering.
3+
The dev containers integration enables seamless creation and management of dev containers in Coder workspaces.
4+
5+
This feature leverages the [`@devcontainers/cli`](https://github.com/devcontainers/cli) and [Docker](https://www.docker.com)
6+
to provide a streamlined development experience.
187

198
## Prerequisites
209

21-
- Coder version 2.22.0 or later
22-
- Coder CLI version 2.22.0 or later
10+
- Coder version 2.24.0 or later
11+
- Coder CLI version 2.24.0 or later
2312
- A template with:
2413
- Dev containers integration enabled
2514
- A Docker-compatible workspace image
@@ -37,63 +26,31 @@ which allows for extensive customization of your development setup.
3726

3827
When a workspace with the dev containers integration starts:
3928

40-
1. The workspace initializes the Docker environment.
41-
1. The integration detects repositories with a `.devcontainer` directory or a
42-
`devcontainer.json` file.
43-
1. The integration builds and starts the dev container based on the
44-
configuration.
29+
1. The integration detects repositories with a `.devcontainer` directory or a `devcontainer.json` file.
30+
1. The integration starts the dev container based on the template and `devcontainer.json`.
4531
1. Your workspace automatically detects the running dev container.
4632

4733
## Features
4834

49-
### Available Now
50-
51-
- Automatic dev container detection from repositories
52-
- Seamless dev container startup during workspace initialization
53-
- Integrated IDE experience in dev containers with VS Code
54-
- Direct service access in dev containers
55-
- Limited SSH access to dev containers
56-
57-
### Coming Soon
58-
59-
- Dev container change detection
60-
- On-demand dev container recreation
61-
- Support for automatic port forwarding inside the container
62-
- Full native SSH support to dev containers
63-
64-
## Limitations during Early Access
35+
### Detection & Lifecycle
6536

66-
During the early access phase, the dev containers integration has the following
67-
limitations:
37+
- Automatic dev container detection from repositories.
38+
- Change detection with rebuild prompts.
39+
- Rebuild containers with one click from the Coder dashboard.
6840

69-
- Changes to the `devcontainer.json` file require manual container recreation
70-
- Automatic port forwarding only works for ports specified in `appPort`
71-
- SSH access requires using the `--container` flag
72-
- Some devcontainer features may not work as expected
41+
### Connectivity
7342

74-
These limitations will be addressed in future updates as the feature matures.
43+
- Full SSH access directly into dev containers (`coder ssh <agent>.<workspace>.me.coder`).
44+
- Automatic port forwarding.
7545

76-
## Comparison with Envbuilder-based Dev Containers
46+
## Known Limitations
7747

78-
| Feature | Dev Containers (Early Access) | Envbuilder Dev Containers |
79-
|----------------|----------------------------------------|----------------------------------------------|
80-
| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder |
81-
| Target users | Individual developers | Platform teams and administrators |
82-
| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder |
83-
| Management | User-controlled | Admin-controlled |
84-
| Requirements | Docker access in workspace | Compatible with more restricted environments |
48+
Currently, dev containers are not compatible with [prebuilt workspaces](../../admin/templates/extending-templates/prebuilt-workspaces.md).
8549

86-
Choose the appropriate solution based on your team's needs and infrastructure
87-
constraints. For additional details on Envbuilder's dev container support, see
88-
the
89-
[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
50+
If your template allows for prebuilt workspaces, do not select a prebuilt workspace if you plan to use a dev container.
9051

9152
## Next Steps
9253

93-
- Explore the [dev container specification](https://containers.dev/) to learn
94-
more about advanced configuration options
95-
- Read about [dev container features](https://containers.dev/features) to
96-
enhance your development environment
97-
- Check the
98-
[VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
99-
for IDE-specific features
54+
- [Dev Container specification](https://containers.dev/)
55+
- [VS Code dev containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
56+
- [Choose an approach to Dev Containers](../../admin/templates/extending-templates/dev-containers-envbuilder.md)

0 commit comments

Comments
 (0)