Skip to content

Commit 26d6222

Browse files
EdwardAngertEdwardAngert
committed
reorganize devcontainers information
1 parent 81dce70 commit 26d6222

File tree

7 files changed

+274
-272
lines changed

7 files changed

+274
-272
lines changed

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

Lines changed: 124 additions & 0 deletions
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/manifest.json

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -215,9 +215,22 @@
215215
},
216216
{
217217
"title": "Dev Containers Integration",
218+
"description": "Run containerized development environments in your Coder workspace using the dev containers specification.",
218219
"path": "./user-guides/devcontainers/index.md",
219220
"icon_path": "./images/icons/container.svg",
220-
"state": ["early access"]
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+
},
228+
{
229+
"title": "Troubleshooting dev containers",
230+
"description": "Diagnose and resolve common issues with dev containers in your Coder workspace.",
231+
"path": "./user-guides/devcontainers/troubleshooting-dev-containers.md"
232+
}
233+
]
221234
},
222235
{
223236
"title": "Dotfiles",

0 commit comments

Comments
 (0)