Skip to content

Commit 280112a

Browse files
bpmctTirzonomatifali
authored
docs: add devcontainer templates (#8256)
* start * start a template * basic structure * Update docs/templates/devcontainers.md Co-authored-by: Sebastiaan ten Pas <sebastiaan@diggimedia.nl> * Update examples/templates/devcontainer-docker/main.tf Co-authored-by: Muhammad Atif Ali <atif@coder.com> * add kubernetes template * mention parameters * fixups * fixes from feedback --------- Co-authored-by: Sebastiaan ten Pas <sebastiaan@diggimedia.nl> Co-authored-by: Muhammad Atif Ali <atif@coder.com>
1 parent 19f5835 commit 280112a

File tree

7 files changed

+570
-0
lines changed

7 files changed

+570
-0
lines changed
251 KB
Loading

docs/manifest.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,12 @@
176176
"path": "./templates/docker-in-workspaces.md",
177177
"icon_path": "./images/icons/docker.svg"
178178
},
179+
{
180+
"title": "Devcontainers",
181+
"description": "Use devcontainers in workspaces",
182+
"path": "./templates/devcontainers.md",
183+
"state": "alpha"
184+
},
179185
{
180186
"title": "Terraform Modules",
181187
"description": "Reuse code across Coder templates",

docs/templates/devcontainers.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Devcontainers (alpha)
2+
3+
[Devcontainers](https://containers.dev) are an open source specification for defining development environments. [envbuilder](https://github.com/coder/envbuilder) is an open source project by Coder that runs devcontainers via Coder templates and your underlying infrastructure.
4+
5+
There are several benefits to adding a devcontainer-compatible template to Coder:
6+
7+
- Drop-in migration from Codespaces (or any existing repositories that use devcontainers)
8+
- Easier to start projects from Coder (new workspace, pick starter devcontainer)
9+
- Developer teams can "bring their own image." No need for platform teams to manage complex images, registries, and CI pipelines.
10+
11+
## How it works
12+
13+
- Coder admins add a devcontainer-compatible template to Coder (envbuilder can run on Docker or Kubernetes)
14+
15+
- Developers enter their repository URL as a [parameter](./parameters.md) when they create their workspace. [envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a container from the `devcontainer.json` specified in the repo.
16+
17+
- Developers can edit the `devcontainer.json` in their workspace to rebuild to iterate on their development environments.
18+
19+
## Example templates
20+
21+
- [Docker](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
22+
- [Kubernetes](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
23+
24+
![Devcontainer parameter screen](../images/templates/devcontainers.png)
25+
26+
[Parameters](./parameters.md) can be used to prompt the user for a repo URL when they are creating a workspace.
27+
28+
## Authentication
29+
30+
You may need to authenticate to your container registry (e.g. Artifactory) or git provider (e.g. GitLab) to use envbuilder. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
31+
32+
## Caching
33+
34+
To improve build times, devcontainers can be cached. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information.
35+
36+
## Other features & known issues
37+
38+
Envbuilder is still under active development. Refer to the [envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more information and to submit feature requests.
Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
name: Devcontainers in Docker
3+
description: Develop using devcontainers in Docker
4+
tags: [local, docker]
5+
icon: /icon/docker.png
6+
---
7+
8+
# devcontainer-docker
9+
10+
Develop using [devcontainers](https://containers.dev) in Docker.
11+
12+
To get started, run `coder templates init`. When prompted, select this template.
13+
Follow the on-screen instructions to proceed.
14+
15+
## How it works
16+
17+
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).
18+
19+
## code-server
20+
21+
`code-server` is installed via the `startup_script` argument in the `coder_agent`
22+
resource block. The `coder_app` resource is defined to access `code-server` through
23+
the dashboard UI over `localhost:13337`.
24+
25+
## Extending this template
26+
27+
See the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to add the following features to your Coder template:
28+
29+
- SSH/TCP docker host
30+
- Registry authentication
31+
- Build args
32+
- Volume mounts
33+
- Custom container spec
34+
- More
35+
36+
We also welcome contributions!
Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
terraform {
2+
required_providers {
3+
coder = {
4+
source = "coder/coder"
5+
version = "0.11.0"
6+
}
7+
docker = {
8+
source = "kreuzwerker/docker"
9+
version = "3.0.2"
10+
}
11+
}
12+
}
13+
14+
data "coder_provisioner" "me" {
15+
}
16+
17+
provider "docker" {
18+
}
19+
20+
data "coder_workspace" "me" {
21+
}
22+
23+
resource "coder_agent" "main" {
24+
arch = data.coder_provisioner.me.arch
25+
os = "linux"
26+
startup_script_timeout = 180
27+
startup_script = <<-EOT
28+
set -e
29+
30+
# install and start code-server
31+
curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0
32+
/tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 &
33+
EOT
34+
dir = "/worskpaces"
35+
36+
# These environment variables allow you to make Git commits right away after creating a
37+
# workspace. Note that they take precedence over configuration defined in ~/.gitconfig!
38+
# You can remove this block if you'd prefer to configure Git manually or using
39+
# dotfiles. (see docs/dotfiles.md)
40+
env = {
41+
GIT_AUTHOR_NAME = "${data.coder_workspace.me.owner}"
42+
GIT_COMMITTER_NAME = "${data.coder_workspace.me.owner}"
43+
GIT_AUTHOR_EMAIL = "${data.coder_workspace.me.owner_email}"
44+
GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}"
45+
}
46+
47+
# The following metadata blocks are optional. They are used to display
48+
# information about your workspace in the dashboard. You can remove them
49+
# if you don't want to display any information.
50+
# For basic resources, you can use the `coder stat` command.
51+
# If you need more control, you can write your own script.
52+
metadata {
53+
display_name = "CPU Usage"
54+
key = "0_cpu_usage"
55+
script = "coder stat cpu"
56+
interval = 10
57+
timeout = 1
58+
}
59+
60+
metadata {
61+
display_name = "RAM Usage"
62+
key = "1_ram_usage"
63+
script = "coder stat mem"
64+
interval = 10
65+
timeout = 1
66+
}
67+
68+
metadata {
69+
display_name = "Home Disk"
70+
key = "3_home_disk"
71+
script = "coder stat disk --path $HOME"
72+
interval = 60
73+
timeout = 1
74+
}
75+
76+
metadata {
77+
display_name = "CPU Usage (Host)"
78+
key = "4_cpu_usage_host"
79+
script = "coder stat cpu --host"
80+
interval = 10
81+
timeout = 1
82+
}
83+
84+
metadata {
85+
display_name = "Memory Usage (Host)"
86+
key = "5_mem_usage_host"
87+
script = "coder stat mem --host"
88+
interval = 10
89+
timeout = 1
90+
}
91+
92+
metadata {
93+
display_name = "Load Average (Host)"
94+
key = "6_load_host"
95+
# get load avg scaled by number of cores
96+
script = <<EOT
97+
echo "`cat /proc/loadavg | awk '{ print $1 }'` `nproc`" | awk '{ printf "%0.2f", $1/$2 }'
98+
EOT
99+
interval = 60
100+
timeout = 1
101+
}
102+
103+
metadata {
104+
display_name = "Swap Usage (Host)"
105+
key = "7_swap_host"
106+
script = <<EOT
107+
free -b | awk '/^Swap/ { printf("%.1f/%.1f", $3/1024.0/1024.0/1024.0, $2/1024.0/1024.0/1024.0) }'
108+
EOT
109+
interval = 10
110+
timeout = 1
111+
}
112+
}
113+
114+
resource "coder_app" "code-server" {
115+
agent_id = coder_agent.main.id
116+
slug = "code-server"
117+
display_name = "code-server"
118+
url = "http://localhost:13337/?folder=/workspaces"
119+
icon = "/icon/code.svg"
120+
subdomain = false
121+
share = "owner"
122+
123+
healthcheck {
124+
url = "http://localhost:13337/healthz"
125+
interval = 5
126+
threshold = 6
127+
}
128+
}
129+
130+
131+
resource "docker_volume" "workspaces" {
132+
name = "coder-${data.coder_workspace.me.id}"
133+
# Protect the volume from being deleted due to changes in attributes.
134+
lifecycle {
135+
ignore_changes = all
136+
}
137+
# Add labels in Docker to keep track of orphan resources.
138+
labels {
139+
label = "coder.owner"
140+
value = data.coder_workspace.me.owner
141+
}
142+
labels {
143+
label = "coder.owner_id"
144+
value = data.coder_workspace.me.owner_id
145+
}
146+
labels {
147+
label = "coder.workspace_id"
148+
value = data.coder_workspace.me.id
149+
}
150+
# This field becomes outdated if the workspace is renamed but can
151+
# be useful for debugging or cleaning out dangling volumes.
152+
labels {
153+
label = "coder.workspace_name_at_creation"
154+
value = data.coder_workspace.me.name
155+
}
156+
}
157+
158+
data "coder_parameter" "repo" {
159+
name = "repo"
160+
display_name = "Repository (auto)"
161+
order = 1
162+
description = "Select a repository to automatically clone and start working with a devcontainer."
163+
mutable = true
164+
option {
165+
name = "vercel/next.js"
166+
description = "The React Framework"
167+
value = "https://github.com/vercel/next.js"
168+
}
169+
option {
170+
name = "home-assistant/core"
171+
description = "🏡 Open source home automation that puts local control and privacy first."
172+
value = "https://github.com/home-assistant/core"
173+
}
174+
option {
175+
name = "discourse/discourse"
176+
description = "A platform for community discussion. Free, open, simple."
177+
value = "https://github.com/discourse/discourse"
178+
}
179+
option {
180+
name = "denoland/deno"
181+
description = "A modern runtime for JavaScript and TypeScript."
182+
value = "https://github.com/denoland/deno"
183+
}
184+
option {
185+
name = "microsoft/vscode"
186+
icon = "/icon/code.svg"
187+
description = "Code editing. Redefined."
188+
value = "https://github.com/microsoft/vscode"
189+
}
190+
option {
191+
name = "Custom"
192+
icon = "/emojis/1f5c3.png"
193+
description = "Specify a custom repo URL below"
194+
value = "custom"
195+
}
196+
}
197+
198+
data "coder_parameter" "custom_repo_url" {
199+
name = "custom_repo"
200+
display_name = "Repository URL (custom)"
201+
order = 2
202+
default = ""
203+
description = "Optionally enter a custom repository URL, see [awesome-devcontainers](https://github.com/manekinekko/awesome-devcontainers)."
204+
mutable = true
205+
}
206+
207+
resource "docker_container" "workspace" {
208+
count = data.coder_workspace.me.start_count
209+
image = "ghcr.io/coder/envbuilder:0.1.3"
210+
# Uses lower() to avoid Docker restriction on container names.
211+
name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}"
212+
# Hostname makes the shell more user friendly: coder@my-workspace:~$
213+
hostname = data.coder_workspace.me.name
214+
# Use the docker gateway if the access URL is 127.0.0.1
215+
env = [
216+
"CODER_AGENT_TOKEN=${coder_agent.main.token}",
217+
"CODER_AGENT_URL=${replace(data.coder_workspace.me.access_url, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}",
218+
"GIT_URL=${data.coder_parameter.repo.value == "custom" ? data.coder_parameter.custom_repo_url.value : data.coder_parameter.repo.value}",
219+
"INIT_SCRIPT=${replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}",
220+
"FALLBACK_IMAGE=codercom/enterprise-base:ubuntu" # This image runs if builds fail
221+
]
222+
host {
223+
host = "host.docker.internal"
224+
ip = "host-gateway"
225+
}
226+
volumes {
227+
container_path = "/workspaces"
228+
volume_name = docker_volume.workspaces.name
229+
read_only = false
230+
}
231+
# Add labels in Docker to keep track of orphan resources.
232+
labels {
233+
label = "coder.owner"
234+
value = data.coder_workspace.me.owner
235+
}
236+
labels {
237+
label = "coder.owner_id"
238+
value = data.coder_workspace.me.owner_id
239+
}
240+
labels {
241+
label = "coder.workspace_id"
242+
value = data.coder_workspace.me.id
243+
}
244+
labels {
245+
label = "coder.workspace_name"
246+
value = data.coder_workspace.me.name
247+
}
248+
}
Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
name: Devcontainers in Kubernetes
3+
description: Develop using devcontainers in Kubernetes
4+
tags: [local, kubernetes]
5+
icon: /icon/kubernetes.png
6+
---
7+
8+
# devcontainer-kubernetes
9+
10+
Develop using [devcontainers](https://containers.dev) in Kubernetes.
11+
12+
To get started, run `coder templates init`. When prompted, select this template.
13+
Follow the on-screen instructions to proceed.
14+
15+
## How it works
16+
17+
Coder supports devcontainers with [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/v2/latest/templates/devcontainers).

0 commit comments

Comments
 (0)