8000 consistent and working examples · coder/coder@df07196 · GitHub
[go: up one dir, main page]

Skip to content

Commit df07196

Browse files 10000
committed
consistent and working examples
1 parent f4db3da commit df07196

File tree

1 file changed

+61
-52
lines changed

1 file changed

+61
-52
lines changed

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

Lines changed: 61 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -19,11 +19,35 @@ When integrated with Coder templates, they provide:
1919

2020
## Prerequisites
2121

22-
Dev containers require Docker to build and run containers.
23-
Ensure your workspace infrastructure has Docker configured with container creation permissions and sufficient resources.
22+
- Dev containers require Docker to build and run containers inside the workspace.
2423

25-
To confirm that Docker is configured correctly, create a test workspace and confirm that `docker ps` runs.
26-
If it doesn't, follow the steps in [Docker in workspaces](./docker-in-workspaces.md).
24+
Ensure your workspace infrastructure has Docker configured with container creation permissions and sufficient resources.
25+
26+
To confirm that Docker is configured correctly, create a test workspace and confirm that `docker ps` runs.
27+
If it doesn't, follow the steps in [Docker in workspaces](./docker-in-workspaces.md).
28+
29+
- The `devcontainers-cli` module requires npm.
30+
31+
- Use an image that already includes npm, such as `codercom/enterprise-node:ubuntu`
32+
- <details><summary>If your template doesn't already include npm, install it at runtime with the `nodejs` module:</summary>
33+
34+
1. This block should be before the `devcontainers-cli` block in `main.tf`:
35+
36+
```terraform
37+
module "nodejs" {
38+
count = data.coder_workspace.me.start_count
39+
source = "dev.registry.coder.com/modules/nodejs/coder"
40+
agent_id = coder_agent.main.id
41+
}
42+
```
43+
44+
1. Add `depends_on` to the `devcontainers-cli` module block:
45+
46+
```terraform
47+
depends_on = [module.nodejs]
48+
```
49+
50+
</details>
2751
2852
## Enable Dev Containers Integration
2953
@@ -50,7 +74,7 @@ to install `@devcontainers/cli` in your workspace:
5074
module "devcontainers-cli" {
5175
count = data.coder_workspace.me.start_count
5276
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
53-
agent_id = coder_agent.dev.id
77+
agent_id = coder_agent.main.id
5478
}
5579
```
5680

@@ -62,12 +86,12 @@ RUN npm install -g @devcontainers/cli
6286

6387
## Define the dev container resource
6488

65-
Point the resource at the folder that contains `devcontainer.json`:
89+
If you don't use [`git_clone`](#clone-the-repository), point the resource at the folder that contains `devcontainer.json`:
6690

6791
```terraform
6892
resource "coder_devcontainer" "project" {
6993
count = data.coder_workspace.me.start_count
70-
agent_id = coder_agent.dev.id
94+
agent_id = coder_agent.main.id
7195
workspace_folder = "/home/coder/project"
7296
}
7397
```
@@ -76,41 +100,26 @@ resource "coder_devcontainer" "project" {
76100

77101
This step is optional, but it ensures that the project is present before the dev container starts.
78102

103+
Note that if you use the `git_clone` module, place it before the `coder_devcontainer` resource< EDBE /div>
104+
and update or replace that resource to point at `/home/coder/project/${module.git_clone[0].folder_name}` so that it is only defined once:
105+
79106
```terraform
80107
module "git_clone" {
81108
count = data.coder_workspace.me.start_count
82109
source = "dev.registry.coder.com/modules/git-clone/coder"
83-
agent_id = coder_agent.dev.id
110+
agent_id = coder_agent.main.id
84111
url = "https://github.com/example/project.git"
85-
path = "/home/coder/project"
112+
base_dir = "/home/coder/project"
86113
}
87114
88115
resource "coder_devcontainer" "project" {
89116
count = data.coder_workspace.me.start_count
90-
agent_id = coder_agent.dev.id
91-
workspace_folder = module.git_clone[0].path
117+
agent_id = coder_agent.main.id
118+
workspace_folder = "/home/coder/project/${module.git_clone[0].folder_name}"
92119
depends_on = [module.git_clone]
93120
}
94121
```
95122

96-
## Configure Automatic Dev Container Startup
97-
98-
The
99-
[`coder_devcontainer`](https://registry.terraform.io/providers/coder/coder/latest/docs/resources/devcontainer)
100-
resource automatically starts a dev container in your workspace, ensuring it's
101-
ready when you access the workspace:
102-
103-
```terraform
104-
resource "coder_devcontainer" "my-repository" {
105-
count = data.coder_workspace.me.start_count
106-
agent_id = coder_agent.dev.id
107-
workspace_folder = "/home/coder/my-repository"
108-
}
109-
```
110-
111-
The `workspace_folder` attribute must specify the location of the dev container's workspace and should point to a
112-
valid project folder that contains a `devcontainer.json` file.
113-
114123
## Dev container features
115124

116125
Enhance your dev container experience with additional features.
@@ -144,22 +153,22 @@ For more advanced use cases, consult the [advanced dev containers doc](./advance
144153
Coder names dev container agents in this order:
145154

146155
1. `customizations.coder.agent.name` in `devcontainer.json`
147-
2. `name` in `devcontainer.json`
148-
3. Directory name that contains the config
149-
4. `devcontainer` (default)
156+
1. `name` in `devcontainer.json`
157+
1. Directory name that contains the config
158+
1. `devcontainer` (default)
150159

151160
### Multiple dev containers
152161

153162
```terraform
154163
resource "coder_devcontainer" "frontend" {
155164
count = data.coder_workspace.me.start_count
156-
agent_id = coder_agent.dev.id
165+
agent_id = coder_agent.main.id
157166
workspace_folder = "/home/coder/frontend"
158167
}
159168
160169
resource "coder_devcontainer" "backend" {
161170
count = data.coder_workspace.me.start_count
162-
agent_id = coder_agent.dev.id
171+
agent_id = coder_agent.main.id
163172
workspace_folder = "/home/coder/backend"
164173
}
165174
```
@@ -181,7 +190,7 @@ terraform {
181190
data "coder_workspace" "me" {}
182191
data "coder_workspace_owner" "me" {}
183192
184-
resource "coder_agent" "dev" {
193+
resource "coder_agent" "main" {
185194
os = "linux"
186195
arch = "amd64"
187196
env = { CODER_AGENT_DEVCONTAINERS_ENABLE = "true" }
@@ -194,28 +203,28 @@ resource "coder_agent" "dev" {
194203
module "devcontainers_cli" {
195204
count = data.coder_workspace.me.start_count
196205
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
197-
agent_id = coder_agent.dev.id
206+
agent_id = coder_agent.main.id
198207
}
199208
200209
module "git_clone" {
201210
count = data.coder_workspace.me.start_count
202211
source = "dev.registry.coder.com/modules/git-clone/coder"
203-
agent_id = coder_agent.dev.id
212+
agent_id = coder_agent.main.id
204213
url = "https://github.com/example/project.git"
205-
path = "/home/coder/project"
214+
base_dir = "/home/coder/project"
206215
}
207216
208217
resource "coder_devcontainer" "project" {
209218
count = data.coder_workspace.me.start_count
210-
agent_id = coder_agent.dev.id
211-
workspace_folder = module.git_clone[0].path
219+
agent_id = coder_agent.main.id
220+
workspace_folder = "/home/coder/project/${module.git_clone[0].folder_name}"
212221
depends_on = [module.git_clone]
213222
}
214223
215224
resource "docker_container" "workspace" {
216225
count = data.coder_workspace.me.start_count
217-
image = "codercom/enterprise-base:ubuntu"
218-
name = "coder-$ta.coder_workspace_owner.me.name}-$ta.coder_workspace.me.name}"
226+
image = "codercom/enterprise-node:ubuntu"
227+
name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
219228
privileged = true # or mount /var/run/docker.sock
220229
}
221230
```
@@ -235,7 +244,7 @@ terraform {
235244
data "coder_workspace" "me" {}
236245
data "coder_workspace_owner" "me" {}
237246
238-
resource "coder_agent" "dev" {
247+
resource "coder_agent" "main" {
239248
os = "linux"
240249
arch = "amd64"
241250
env = { CODER_AGENT_DEVCONTAINERS_ENABLE = "true" }
@@ -247,45 +256,45 @@ resource "coder_agent" "dev" {
247256
module "devcontainers_cli" {
248257
count = data.coder_workspace.me.start_count
249258
source = "dev.registry.coder.com/modules/devcontainers-cli/coder"
250-
agent_id = coder_agent.dev.id
259+
agent_id = coder_agent.main.id
251260
}
252261
253262
module "git_clone" {
254263
count = data.coder_workspace.me.start_count
255264
source = "dev.registry.coder.com/modules/git-clone/coder"
256-
agent_id = coder_agent.dev.id
265+
agent_id = coder_agent.main.id
257266
url = "https://github.com/example/project.git"
258-
path = "/home/coder/project"
267+
base_dir = "/home/coder/project"
259268
}
260269
261270
resource "coder_devcontainer" "project" {
262271
count = data.coder_workspace.me.start_count
263-
agent_id = coder_agent.dev.id
264-
workspace_folder = module.git_clone[0].path
272+
agent_id = coder_agent.main.id
273+
workspace_folder = "/home/coder/project/${module.git_clone[0].folder_name}"
265274
depends_on = [module.git_clone]
266275
}
267276
268277
resource "kubernetes_pod" "workspace" {
269278
count = data.coder_workspace.me.start_count
270279
271280
metadata {
272-
name = "coder-$ta.coder_workspace_owner.me.name}-$ta.coder_workspace.me.name}"
281+
name = "coder-${data.coder_workspace_owner.me.name}-${lower(data.coder_workspace.me.name)}"
273282
namespace = "coder-workspaces"
274283
}
275284
276285
spec {
277286
container {
278-
name = "dev"
287+
name = "main"
279288
image = "codercom/enterprise-base:ubuntu"
280289
281290
security_context { privileged = true } # or use Sysbox / rootless
282-
env { name = "CODER_AGENT_TOKEN" value = coder_agent.dev.token }
291+
env { name = "CODER_AGENT_TOKEN" value = coder_agent.main.token }
283292
}
284293
}
285294
}
286295
```
287296

288-
</detail>
297+
</details>
289298

290299
## Troubleshoot common issues
291300

0 commit comments

Comments
 (0)
0