- Notifications
You must be signed in to change notification settings - Fork1k
docs: add devcontainer templates#8256
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to ourterms of service andprivacy statement. We’ll occasionally send you account related emails.
Already on GitHub?Sign in to your account
Merged
Uh oh!
There was an error while loading.Please reload this page.
Merged
Changes fromall commits
Commits
Show all changes
12 commits Select commitHold shift + click to select a range
4aec9cf start
bpmct68683e5 start a template
bpmct23aff12 Merge branch 'main' into bpmct/devcontainers-docs
bpmct521cd5f basic structure
bpmct0afc833 Update docs/templates/devcontainers.md
bpmctc3f85d4 Update examples/templates/devcontainer-docker/main.tf
bpmct1c99252 add kubernetes template
bpmct5ccbc8e Merge branch 'bpmct/devcontainers-docs' of https://github.com/coder/c…
bpmct419bb5a mention parameters
bpmct8c78d4d fixups
bpmctc072e3f Merge branch 'main' into bpmct/devcontainers-docs
bpmct4a70023 fixes from feedback
bpmctFile filter
Filter by extension
Conversations
Failed to load comments.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Jump to
Jump to file
Failed to load files.
Loading
Uh oh!
There was an error while loading.Please reload this page.
Diff view
Diff view
There are no files selected for viewing
Binary file addeddocs/images/templates/devcontainers.png
Loading
Sorry, something went wrong.Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletionsdocs/manifest.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
38 changes: 38 additions & 0 deletionsdocs/templates/devcontainers.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| # Devcontainers (alpha) | ||
| [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. | ||
| There are several benefits to adding a devcontainer-compatible template to Coder: | ||
| - Drop-in migration from Codespaces (or any existing repositories that use devcontainers) | ||
| - Easier to start projects from Coder (new workspace, pick starter devcontainer) | ||
| - Developer teams can "bring their own image." No need for platform teams to manage complex images, registries, and CI pipelines. | ||
| ## How it works | ||
| - Coder admins add a devcontainer-compatible template to Coder (envbuilder can run on Docker or Kubernetes) | ||
| - 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. | ||
| - Developers can edit the `devcontainer.json` in their workspace to rebuild to iterate on their development environments. | ||
| ## Example templates | ||
| - [Docker](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker) | ||
| - [Kubernetes](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes) | ||
|  | ||
| [Parameters](./parameters.md) can be used to prompt the user for a repo URL when they are creating a workspace. | ||
| ## Authentication | ||
| 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. | ||
| ## Caching | ||
| To improve build times, devcontainers can be cached. Refer to the [envbuilder documentation](https://github.com/coder/envbuilder/) for more information. | ||
| ## Other features & known issues | ||
| 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. |
36 changes: 36 additions & 0 deletionsexamples/templates/devcontainer-docker/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| --- | ||
| name: Devcontainers in Docker | ||
| description: Develop using devcontainers in Docker | ||
| tags: [local, docker] | ||
| icon: /icon/docker.png | ||
| --- | ||
| # devcontainer-docker | ||
| Develop using [devcontainers](https://containers.dev) in Docker. | ||
| To get started, run `coder templates init`. When prompted, select this template. | ||
| Follow the on-screen instructions to proceed. | ||
| ## How it works | ||
| 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). | ||
| ## code-server | ||
| `code-server` is installed via the `startup_script` argument in the `coder_agent` | ||
| resource block. The `coder_app` resource is defined to access `code-server` through | ||
| the dashboard UI over `localhost:13337`. | ||
| ## Extending this template | ||
| See the [kreuzwerker/docker](https://registry.terraform.io/providers/kreuzwerker/docker) Terraform provider documentation to add the following features to your Coder template: | ||
| - SSH/TCP docker host | ||
| - Registry authentication | ||
| - Build args | ||
| - Volume mounts | ||
| - Custom container spec | ||
| - More | ||
| We also welcome contributions! |
248 changes: 248 additions & 0 deletionsexamples/templates/devcontainer-docker/main.tf
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,248 @@ | ||
| terraform { | ||
| required_providers { | ||
| coder = { | ||
| source = "coder/coder" | ||
| version = "0.11.0" | ||
| } | ||
| docker = { | ||
| source = "kreuzwerker/docker" | ||
| version = "3.0.2" | ||
| } | ||
| } | ||
| } | ||
| data "coder_provisioner" "me" { | ||
| } | ||
| provider "docker" { | ||
| } | ||
| data "coder_workspace" "me" { | ||
| } | ||
| resource "coder_agent" "main" { | ||
| arch = data.coder_provisioner.me.arch | ||
| os = "linux" | ||
| startup_script_timeout = 180 | ||
| startup_script = <<-EOT | ||
| set -e | ||
| # install and start code-server | ||
| curl -fsSL https://code-server.dev/install.sh | sh -s -- --method=standalone --prefix=/tmp/code-server --version 4.11.0 | ||
| /tmp/code-server/bin/code-server --auth none --port 13337 >/tmp/code-server.log 2>&1 & | ||
| EOT | ||
| dir = "/worskpaces" | ||
| # These environment variables allow you to make Git commits right away after creating a | ||
| # workspace. Note that they take precedence over configuration defined in ~/.gitconfig! | ||
| # You can remove this block if you'd prefer to configure Git manually or using | ||
| # dotfiles. (see docs/dotfiles.md) | ||
| env = { | ||
| GIT_AUTHOR_NAME = "${data.coder_workspace.me.owner}" | ||
| GIT_COMMITTER_NAME = "${data.coder_workspace.me.owner}" | ||
| GIT_AUTHOR_EMAIL = "${data.coder_workspace.me.owner_email}" | ||
| GIT_COMMITTER_EMAIL = "${data.coder_workspace.me.owner_email}" | ||
| } | ||
| # The following metadata blocks are optional. They are used to display | ||
| # information about your workspace in the dashboard. You can remove them | ||
| # if you don't want to display any information. | ||
| # For basic resources, you can use the `coder stat` command. | ||
| # If you need more control, you can write your own script. | ||
| metadata { | ||
| display_name = "CPU Usage" | ||
| key = "0_cpu_usage" | ||
| script = "coder stat cpu" | ||
| interval = 10 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "RAM Usage" | ||
| key = "1_ram_usage" | ||
| script = "coder stat mem" | ||
| interval = 10 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "Home Disk" | ||
| key = "3_home_disk" | ||
| script = "coder stat disk --path $HOME" | ||
| interval = 60 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "CPU Usage (Host)" | ||
| key = "4_cpu_usage_host" | ||
| script = "coder stat cpu --host" | ||
| interval = 10 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "Memory Usage (Host)" | ||
| key = "5_mem_usage_host" | ||
| script = "coder stat mem --host" | ||
| interval = 10 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "Load Average (Host)" | ||
| key = "6_load_host" | ||
| # get load avg scaled by number of cores | ||
| script = <<EOT | ||
| echo "`cat /proc/loadavg | awk '{ print $1 }'` `nproc`" | awk '{ printf "%0.2f", $1/$2 }' | ||
| EOT | ||
| interval = 60 | ||
| timeout = 1 | ||
| } | ||
| metadata { | ||
| display_name = "Swap Usage (Host)" | ||
| key = "7_swap_host" | ||
| script = <<EOT | ||
| free -b | awk '/^Swap/ { printf("%.1f/%.1f", $3/1024.0/1024.0/1024.0, $2/1024.0/1024.0/1024.0) }' | ||
| EOT | ||
| interval = 10 | ||
| timeout = 1 | ||
| } | ||
| } | ||
| resource "coder_app" "code-server" { | ||
| agent_id = coder_agent.main.id | ||
| slug = "code-server" | ||
| display_name = "code-server" | ||
| url = "http://localhost:13337/?folder=/workspaces" | ||
| icon = "/icon/code.svg" | ||
| subdomain = false | ||
| share = "owner" | ||
| healthcheck { | ||
| url = "http://localhost:13337/healthz" | ||
| interval = 5 | ||
| threshold = 6 | ||
| } | ||
| } | ||
| resource "docker_volume" "workspaces" { | ||
| name = "coder-${data.coder_workspace.me.id}" | ||
| # Protect the volume from being deleted due to changes in attributes. | ||
| lifecycle { | ||
| ignore_changes = all | ||
| } | ||
| # Add labels in Docker to keep track of orphan resources. | ||
| labels { | ||
| label = "coder.owner" | ||
| value = data.coder_workspace.me.owner | ||
| } | ||
| labels { | ||
| label = "coder.owner_id" | ||
| value = data.coder_workspace.me.owner_id | ||
| } | ||
| labels { | ||
| label = "coder.workspace_id" | ||
| value = data.coder_workspace.me.id | ||
| } | ||
| # This field becomes outdated if the workspace is renamed but can | ||
| # be useful for debugging or cleaning out dangling volumes. | ||
| labels { | ||
| label = "coder.workspace_name_at_creation" | ||
| value = data.coder_workspace.me.name | ||
| } | ||
| } | ||
| data "coder_parameter" "repo" { | ||
| name = "repo" | ||
| display_name = "Repository (auto)" | ||
| order = 1 | ||
| description = "Select a repository to automatically clone and start working with a devcontainer." | ||
| mutable = true | ||
| option { | ||
| name = "vercel/next.js" | ||
| description = "The React Framework" | ||
| value = "https://github.com/vercel/next.js" | ||
| } | ||
| option { | ||
| name = "home-assistant/core" | ||
| description = "🏡 Open source home automation that puts local control and privacy first." | ||
| value = "https://github.com/home-assistant/core" | ||
| } | ||
| option { | ||
| name = "discourse/discourse" | ||
| description = "A platform for community discussion. Free, open, simple." | ||
| value = "https://github.com/discourse/discourse" | ||
| } | ||
| option { | ||
| name = "denoland/deno" | ||
| description = "A modern runtime for JavaScript and TypeScript." | ||
| value = "https://github.com/denoland/deno" | ||
| } | ||
| option { | ||
| name = "microsoft/vscode" | ||
| icon = "/icon/code.svg" | ||
| description = "Code editing. Redefined." | ||
| value = "https://github.com/microsoft/vscode" | ||
| } | ||
| option { | ||
| name = "Custom" | ||
| icon = "/emojis/1f5c3.png" | ||
| description = "Specify a custom repo URL below" | ||
| value = "custom" | ||
| } | ||
| } | ||
| data "coder_parameter" "custom_repo_url" { | ||
| name = "custom_repo" | ||
| display_name = "Repository URL (custom)" | ||
| order = 2 | ||
| default = "" | ||
| description = "Optionally enter a custom repository URL, see [awesome-devcontainers](https://github.com/manekinekko/awesome-devcontainers)." | ||
| mutable = true | ||
| } | ||
| resource "docker_container" "workspace" { | ||
| count = data.coder_workspace.me.start_count | ||
| image = "ghcr.io/coder/envbuilder:0.1.3" | ||
| # Uses lower() to avoid Docker restriction on container names. | ||
| name = "coder-${data.coder_workspace.me.owner}-${lower(data.coder_workspace.me.name)}" | ||
| # Hostname makes the shell more user friendly: coder@my-workspace:~$ | ||
| hostname = data.coder_workspace.me.name | ||
| # Use the docker gateway if the access URL is 127.0.0.1 | ||
| env = [ | ||
| "CODER_AGENT_TOKEN=${coder_agent.main.token}", | ||
| "CODER_AGENT_URL=${replace(data.coder_workspace.me.access_url, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}", | ||
| "GIT_URL=${data.coder_parameter.repo.value == "custom" ? data.coder_parameter.custom_repo_url.value : data.coder_parameter.repo.value}", | ||
| "INIT_SCRIPT=${replace(coder_agent.main.init_script, "/localhost|127\\.0\\.0\\.1/", "host.docker.internal")}", | ||
| "FALLBACK_IMAGE=codercom/enterprise-base:ubuntu" # This image runs if builds fail | ||
| ] | ||
| host { | ||
| host = "host.docker.internal" | ||
| ip = "host-gateway" | ||
| } | ||
| volumes { | ||
| container_path = "/workspaces" | ||
| volume_name = docker_volume.workspaces.name | ||
| read_only = false | ||
| } | ||
| # Add labels in Docker to keep track of orphan resources. | ||
| labels { | ||
| label = "coder.owner" | ||
| value = data.coder_workspace.me.owner | ||
| } | ||
| labels { | ||
| label = "coder.owner_id" | ||
| value = data.coder_workspace.me.owner_id | ||
| } | ||
| labels { | ||
| label = "coder.workspace_id" | ||
| value = data.coder_workspace.me.id | ||
| } | ||
| labels { | ||
| label = "coder.workspace_name" | ||
| value = data.coder_workspace.me.name | ||
| } | ||
| } |
17 changes: 17 additions & 0 deletionsexamples/templates/devcontainer-kubernetes/README.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| --- | ||
| name: Devcontainers in Kubernetes | ||
| description: Develop using devcontainers in Kubernetes | ||
| tags: [local, kubernetes] | ||
| icon: /icon/kubernetes.png | ||
| --- | ||
| # devcontainer-kubernetes | ||
| Develop using [devcontainers](https://containers.dev) in Kubernetes. | ||
| To get started, run `coder templates init`. When prompted, select this template. | ||
| Follow the on-screen instructions to proceed. | ||
| ## How it works | ||
| 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). |
Oops, something went wrong.
Uh oh!
There was an error while loading.Please reload this page.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.