Skip to content

Commit 3a61ec9

Browse files
mafredrimafredri
committed
amend pr comments
1 parent de5fbfc commit 3a61ec9

File tree

1 file changed

+50
-9
lines changed

1 file changed

+50
-9
lines changed

‎docs/early-access/devcontainers.md

Lines changed: 50 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -27,21 +27,28 @@ experience.
2727

2828
## Features
2929

30+
### Available Now
31+
3032
- Automatic dev container detection from repositories
3133
- Seamless dev container startup during workspace initialization
3234
- Integrated IDE experience in dev containers with VS Code
3335
- Direct service access in dev containers
34-
- Native SSH access to dev containers
35-
- Dev container change detection (coming soon)
36-
- On-demand dev container recreation (coming soon)
36+
- Limited SSH access to dev containers
37+
38+
### Coming Soon
39+
40+
- Dev container change detection
41+
- On-demand dev container recreation
42+
- Support for automatic port forwarding inside the container
43+
- Full native SSH support to dev containers
3744

3845
## Prerequisites
3946

4047
- Coder version 2.22.0 or later
4148
- Coder CLI version 2.22.0 or later
4249
- Dev containers integration enabled in your template(s)
4350
- Docker-compatible workspace image in the template(s)
44-
- Appropriate permissions to execute Docker commands
51+
- Appropriate permissions to execute Docker commands inside your workspace
4552

4653
## How It Works
4754

@@ -81,6 +88,8 @@ module "devcontainers-cli" {
8188
}
8289
```
8390

91+
Alternatively, install the devcontainer CLI manually in your base image.
92+
8493
### Configure Automatic Dev Container Startup
8594

8695
The
@@ -108,6 +117,28 @@ resource "coder_devcontainer" "my-repository" {
108117
> module to ensure your repository is cloned into the workspace folder and ready
109118
> for automatic startup.
110119
120+
### Enable Dev Containers Integration
121+
122+
To enable the dev containers integration in your workspace, you must set the
123+
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your
124+
workspace container:
125+
126+
```terraform
127+
resource "docker_container" "workspace" {
128+
count = data.coder_workspace.me.start_count
129+
image = "codercom/oss-dogfood:latest"
130+
env = [
131+
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
132+
# ... Other environment variables.
133+
]
134+
# ... Other container configuration.
135+
}
136+
```
137+
138+
This environment variable is required for the Coder agent to detect and manage
139+
dev containers. Without it, the agent will not attempt to start or connect to
140+
dev containers even if the `coder_devcontainer` resource is defined.
141+
111142
### Complete Template Example
112143

113144
Here's a simplified template example that enables the dev containers
@@ -151,9 +182,9 @@ resource "docker_container" "workspace" {
151182
image = "codercom/oss-dogfood:latest"
152183
env = [
153184
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
154-
# ...
185+
# ... Other environment variables.
155186
]
156-
# ...
187+
# ... Other container configuration.
157188
}
158189
```
159190

@@ -198,6 +229,11 @@ During the early access phase, port forwarding is limited to ports defined via
198229
[`appPort`](https://containers.dev/implementors/json_reference/#image-specific)
199230
in your `devcontainer.json` file.
200231

232+
> [!NOTE]
233+
>
234+
> Support for automatic port forwarding via the `forwardPorts` property in
235+
> `devcontainer.json` is planned for a future release.
236+
201237
For example, with this `devcontainer.json` configuration:
202238

203239
```json
@@ -259,23 +295,28 @@ These limitations will be addressed in future updates as the feature matures.
259295
## Comparison with Envbuilder-based Dev Containers
260296

261297
| Feature | Dev Containers (Early Access) | Envbuilder Dev Containers |
262-
|----------------|----------------------------------------|----------------------------------------------|
298+
| -------------- | -------------------------------------- | -------------------------------------------- |
263299
| Implementation | Direct `@devcontainers/cli` and Docker | Coder's Envbuilder |
264300
| Target users | Individual developers | Platform teams and administrators |
265301
| Configuration | Standard `devcontainer.json` | Terraform templates with Envbuilder |
266302
| Management | User-controlled | Admin-controlled |
267303
| Requirements | Docker access in workspace | Compatible with more restricted environments |
268304

269305
Choose the appropriate solution based on your team's needs and infrastructure
270-
constraints.
306+
constraints. For additional details on Envbuilder's dev container support, see
307+
the
308+
[Envbuilder devcontainer spec support documentation](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md).
271309

272310
## Troubleshooting
273311

274312
### Dev Container Not Starting
275313

276314
If your dev container fails to start:
277315

278-
1. Check the workspace logs for detailed error messages
316+
1. Check the agent logs for error messages:
317+
- `/tmp/coder-agent.log`
318+
- `/tmp/coder-startup-script.log`
319+
- `/tmp/coder-script-[script_id].log`
279320
2. Verify that Docker is running in your workspace
280321
3. Ensure the `devcontainer.json` file is valid
281322
4. Check that the repository has been cloned correctly

0 commit comments

Comments
 (0)