Skip to content

Commit a226a75

Browse files
mafredriEdwardAngert
mafredri
and
EdwardAngert
authored
docs: add early access dev container docs (#17613)
This change documents the early access dev containers integration and how to enable it, what features are available and what limitations exist at the time of writing. --------- Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
1 parent ef11d4f commit a226a75

File tree

9 files changed

+363
-0
lines changed

9 files changed

+363
-0
lines changed

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

+124
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,124 @@
1+
# Configure a template for dev containers
2+
3+
To enable dev containers in workspaces, configure your template with the dev containers
4+
modules and configurations outlined in this doc.
5+
6+
## Install the Dev Containers CLI
7+
8+
Use the
9+
[devcontainers-cli](https://registry.coder.com/modules/devcontainers-cli) module
10+
to ensure the `@devcontainers/cli` is installed in your workspace:
11+
12+
```terraform
13+
module "devcontainers-cli" {
14+
count = data.coder_workspace.me.start_count
15+
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
16+
agent_id = coder_agent.dev.id
17+
}
18+
```
19+
20+
Alternatively, install the devcontainer CLI manually in your base image.
21+
22+
## Configure Automatic Dev Container Startup
23+
24+
The
25+
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
26+
resource automatically starts a dev container in your workspace, ensuring it's
27+
ready when you access the workspace:
28+
29+
```terraform
30+
resource "coder_devcontainer" "my-repository" {
31+
count = data.coder_workspace.me.start_count
32+
agent_id = coder_agent.dev.id
33+
workspace_folder = "/home/coder/my-repository"
34+
}
35+
```
36+
37+
> [!NOTE]
38+
>
39+
> The `workspace_folder` attribute must specify the location of the dev
40+
> container's workspace and should point to a valid project folder containing a
41+
> `devcontainer.json` file.
42+
43+
<!-- nolint:MD028/no-blanks-blockquote -->
44+
45+
> [!TIP]
46+
>
47+
> Consider using the [`git-clone`](https://registry.coder.com/modules/git-clone)
48+
> module to ensure your repository is cloned into the workspace folder and ready
49+
> for automatic startup.
50+
51+
## Enable Dev Containers Integration
52+
53+
To enable the dev containers integration in your workspace, you must set the
54+
`CODER_AGENT_DEVCONTAINERS_ENABLE` environment variable to `true` in your
55+
workspace container:
56+
57+
```terraform
58+
resource "docker_container" "workspace" {
59+
count = data.coder_workspace.me.start_count
60+
image = "codercom/oss-dogfood:latest"
61+
env = [
62+
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
63+
# ... Other environment variables.
64+
]
65+
# ... Other container configuration.
66+
}
67+
```
68+
69+
This environment variable is required for the Coder agent to detect and manage
70+
dev containers. Without it, the agent will not attempt to start or connect to
71+
dev containers even if the `coder_devcontainer` resource is defined.
72+
73+
## Complete Template Example
74+
75+
Here's a simplified template example that enables the dev containers
76+
integration:
77+
78+
```terraform
79+
terraform {
80+
required_providers {
81+
coder = { source = "coder/coder" }
82+
docker = { source = "kreuzwerker/docker" }
83+
}
84+
}
85+
86+
provider "coder" {}
87+
data "coder_workspace" "me" {}
88+
data "coder_workspace_owner" "me" {}
89+
90+
resource "coder_agent" "dev" {
91+
arch = "amd64"
92+
os = "linux"
93+
startup_script_behavior = "blocking"
94+
startup_script = "sudo service docker start"
95+
shutdown_script = "sudo service docker stop"
96+
# ...
97+
}
98+
99+
module "devcontainers-cli" {
100+
count = data.coder_workspace.me.start_count
101+
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
102+
agent_id = coder_agent.dev.id
103+
}
104+
105+
resource "coder_devcontainer" "my-repository" {
106+
count = data.coder_workspace.me.start_count
107+
agent_id = coder_agent.dev.id
108+
workspace_folder = "/home/coder/my-repository"
109+
}
110+
111+
resource "docker_container" "workspace" {
112+
count = data.coder_workspace.me.start_count
113+
image = "codercom/oss-dogfood:latest"
114+
env = [
115+
"CODER_AGENT_DEVCONTAINERS_ENABLE=true",
116+
# ... Other environment variables.
117+
]
118+
# ... Other container configuration.
119+
}
120+
```
121+
122+
## Next Steps
123+
124+
- [Dev Containers Integration](../../../user-guides/devcontainers/index.md)

‎docs/admin/templates/index.md

+3
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,9 @@ needs of different teams.
5050
create and publish images for use within Coder workspaces & templates.
5151
- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
5252
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).
5356
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
5457
Configure your template to prevent certain resources from being destroyed
5558
(e.g. user disks).

‎docs/images/user-guides/devcontainers/devcontainer-agent-ports.png

133 KB
Loading

‎docs/images/user-guides/devcontainers/devcontainer-web-terminal.png

49.8 KB
Loading

‎docs/manifest.json

+21
Original file line numberDiff line numberDiff line change
@@ -213,6 +213,27 @@
213213
"path": "./user-guides/workspace-lifecycle.md",
214214
"icon_path": "./images/icons/circle-dot.svg"
215215
},
216+
{
217+
"title": "Dev Containers Integration",
218+
"description": "Run containerized development environments in your Coder workspace using the dev containers specification.",
219+
"path": "./user-guides/devcontainers/index.md",
220+
"icon_path": "./images/icons/container.svg",
221+
"state": ["early access"],
222+
"children": [
223+
{
224+
"title": "Working with dev containers",
225+
"description": "Access dev containers via SSH, your IDE, or web terminal.",
226+
"path": "./user-guides/devcontainers/working-with-dev-containers.md",
227+
"state": ["early access"]
228+
},
229+
{
230+
"title": "Troubleshooting dev containers",
231+
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",
232+
"path": "./user-guides/devcontainers/troubleshooting-dev-containers.md",
233+
"state": ["early access"]
234+
}
235+
]
236+
},
216237
{
217238
"title": "Dotfiles",
218239
"description": "Personalize your environment with dotfiles",

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

+99
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Dev Containers Integration
2+
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.
18+
19+
## Prerequisites
20+
21+
- Coder version 2.22.0 or later
22+
- Coder CLI version 2.22.0 or later
23+
- A template with:
24+
- Dev containers integration enabled
25+
- A Docker-compatible workspace image
26+
- Appropriate permissions to execute Docker commands inside your workspace
27+
28+
## How It Works
29+
30+
The dev containers integration utilizes the `devcontainer` command from
31+
[`@devcontainers/cli`](https://github.com/devcontainers/cli) to manage dev
32+
containers within your Coder workspace.
33+
This command provides comprehensive functionality for creating, starting, and managing dev containers.
34+
35+
Dev environments are configured through a standard `devcontainer.json` file,
36+
which allows for extensive customization of your development setup.
37+
38+
When a workspace with the dev containers integration starts:
39+
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.
45+
1. Your workspace automatically detects the running dev container.
46+
47+
## Features
48+
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
65+
66+
During the early access phase, the dev containers integration has the following
67+
limitations:
68+
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
73+
74+
These limitations will be addressed in future updates as the feature matures.
75+
76+
## Comparison with Envbuilder-based Dev Containers
77+
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 |
85+
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).
90+
91+
## Next Steps
92+
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

‎docs/user-guides/devcontainers/troubleshooting-dev-containers.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Troubleshooting dev containers
2+
3+
## Dev Container Not Starting
4+
5+
If your dev container fails to start:
6+
7+
1. Check the agent logs for error messages:
8+
9+
- `/tmp/coder-agent.log`
10+
- `/tmp/coder-startup-script.log`
11+
- `/tmp/coder-script-[script_id].log`
12+
13+
1. Verify that Docker is running in your workspace.
14+
1. Ensure the `devcontainer.json` file is valid.
15+
1. Check that the repository has been cloned correctly.
16+
1. Verify the resource limits in your workspace are sufficient.

‎docs/user-guides/devcontainers/working-with-dev-containers.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Working with Dev Containers
2+
3+
The dev container integration appears in your Coder dashboard, providing a
4+
visual representation of the running environment:
5+
6+
![Dev container integration in Coder dashboard](../../images/user-guides/devcontainers/devcontainer-agent-ports.png)
7+
8+
## SSH Access
9+
10+
You can SSH into your dev container directly using the Coder CLI:
11+
12+
```console
13+
coder ssh --container keen_dijkstra my-workspace
14+
```
15+
16+
> [!NOTE]
17+
>
18+
> SSH access is not yet compatible with the `coder config-ssh` command for use
19+
> with OpenSSH. You would need to manually modify your SSH config to include the
20+
> `--container` flag in the `ProxyCommand`.
21+
22+
## Web Terminal Access
23+
24+
Once your workspace and dev container are running, you can use the web terminal
25+
in the Coder interface to execute commands directly inside the dev container.
26+
27+
![Coder web terminal with dev container](../../images/user-guides/devcontainers/devcontainer-web-terminal.png)
28+
29+
## IDE Integration (VS Code)
30+
31+
You can open your dev container directly in VS Code by:
32+
33+
1. Selecting "Open in VS Code Desktop" from the Coder web interface
34+
2. Using the Coder CLI with the container flag:
35+
36+
```console
37+
coder open vscode --container keen_dijkstra my-workspace
38+
```
39+
40+
While optimized for VS Code, other IDEs with dev containers support may also
41+
work.
42+
43+
## Port Forwarding
44+
45+
During the early access phase, port forwarding is limited to ports defined via
46+
[`appPort`](https://containers.dev/implementors/json_reference/#image-specific)
47+
in your `devcontainer.json` file.
48+
49+
> [!NOTE]
50+
>
51+
> Support for automatic port forwarding via the `forwardPorts` property in
52+
> `devcontainer.json` is planned for a future release.
53+
54+
For example, with this `devcontainer.json` configuration:
55+
56+
```json
57+
{
58+
"appPort": ["8080:8080", "4000:3000"]
59+
}
60+
```
61+
62+
You can forward these ports to your local machine using:
63+
64+
```console
65+
coder port-forward my-workspace --tcp 8080,4000
66+
```
67+
68+
This forwards port 8080 (local) -> 8080 (agent) -> 8080 (dev container) and port
69+
4000 (local) -> 4000 (agent) -> 3000 (dev container).
70+
71+
## Dev Container Features
72+
73+
You can use standard dev container features in your `devcontainer.json` file.
74+
Coder also maintains a
75+
[repository of features](https://github.com/coder/devcontainer-features) to
76+
enhance your development experience.
77+
78+
Currently available features include [code-server](https://github.com/coder/devcontainer-features/blob/main/src/code-server).
79+
80+
To use the code-server feature, add the following to your `devcontainer.json`:
81+
82+
```json
83+
{
84+
"features": {
85+
"ghcr.io/coder/devcontainer-features/code-server:1": {
86+
"port": 13337,
87+
"host": "0.0.0.0"
88+
}
89+
},
90+
"appPort": ["13337:13337"]
91+
}
92+
```
93+
94+
> [!NOTE]
95+
>
96+
> Remember to include the port in the `appPort` section to ensure proper port
97+
> forwarding.

‎docs/user-guides/index.md

+3
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,7 @@ These are intended for end-user flows only. If you are an administrator, please
77
refer to our docs on configuring [templates](../admin/index.md) or the
88
[control plane](../admin/index.md).
99

10+
Check out our [early access features](../install/releases/feature-stages.md) for upcoming
11+
functionality, including [Dev Containers integration](../user-guides/devcontainers/index.md).
12+
1013
<children></children>

0 commit comments

Comments
 (0)