coder · mafredri · Jul 3, 2025 · Jul 3, 2025 · Jul 3, 2025 · Jul 3, 2025
diff --git a/cli/testdata/coder_templates_init_--help.golden b/cli/testdata/coder_templates_init_--help.golden
@@ -6,7 +6,7 @@ USAGE:
   Get started with a templated template.
 
 OPTIONS:
-      --id aws-devcontainer|aws-linux|aws-windows|azure-linux|digitalocean-linux|docker|docker-devcontainer|gcp-devcontainer|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|kubernetes-devcontainer|nomad-docker|scratch
+      --id aws-devcontainer|aws-linux|aws-windows|azure-linux|digitalocean-linux|docker|docker-devcontainer|docker-envbuilder|gcp-devcontainer|gcp-linux|gcp-vm-container|gcp-windows|kubernetes|kubernetes-devcontainer|nomad-docker|scratch
           Specify a given example template by ID.
 
 ———

diff --git a/docs/reference/cli/templates_init.md b/docs/reference/cli/templates_init.md
diff --git a/examples/examples.gen.json b/examples/examples.gen.json
@@ -83,15 +83,29 @@
 	{
 		"id": "docker-devcontainer",
 		"url": "",
-		"name": "Docker (Devcontainer)",
+		"name": "Docker-in-Docker Dev Containers",
+		"description": "Provision Docker containers as Coder workspaces running Dev Containers via Docker-in-Docker.",
+		"icon": "/icon/docker.png",
+		"tags": [
+			"docker",
+			"container",
+			"devcontainer"
+		],
+		"markdown": "\n# Remote Development on Dev Containers\n\nProvision Docker containers as [Coder workspaces](https://coder.com/docs/workspaces) running [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) via Docker-in-Docker.\n\n\u003c!-- TODO: Add screenshot --\u003e\n\n## Prerequisites\n\n### Infrastructure\n\nThe VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:\n\n```sh\n# Add coder user to Docker group\nsudo adduser coder docker\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nThis example uses the `codercom/enterprise-node:ubuntu` Docker image as a base image for the workspace. It includes necessary tools like Docker and Node.js, which are required for running Dev Containers via the `@devcontainers/cli` tool.\n\nThis template provisions the following resources:\n\n- Docker image (built by Docker socket and kept locally)\n- Docker container (ephemeral)\n- Docker volume (persistent on `/home/coder`)\n- Docker volume (persistent on `/var/lib/docker`)\n\nThis means, when the workspace restarts, any tools or files outside of the home directory or docker library are not persisted.\n\nFor devcontainers running inside the workspace, data persistence is dependent on each projects `devcontainer.json` configuration.\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n"
+	},
+	{
+		"id": "docker-envbuilder",
+		"url": "",
+		"name": "Docker (Envbuilder)",
 		"description": "Provision envbuilder containers as Coder workspaces",
 		"icon": "/icon/docker.png",
 		"tags": [
 			"container",
 			"docker",
-			"devcontainer"
+			"devcontainer",
+			"envbuilder"
 		],
-		"markdown": "\n# Remote Development on Docker Containers (with Devcontainers)\n\nProvision Devcontainers as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.\n\n## Prerequisites\n\n### Infrastructure\n\nCoder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:\n\n```shell\n# Add coder user to Docker group\nsudo usermod -aG docker coder\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nCoder supports Devcontainers via [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/templates/dev-containers).\n\nThis template provisions the following resources:\n\n- Envbuilder cached image (conditional, persistent) using [`terraform-provider-envbuilder`](https://github.com/coder/terraform-provider-envbuilder)\n- Docker image (persistent) using [`envbuilder`](https://github.com/coder/envbuilder)\n- Docker container (ephemeral)\n- Docker volume (persistent on `/workspaces`)\n\nThe Git repository is cloned inside the `/workspaces` volume if not present.\nAny local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.\nKeep in mind that any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.\nEdit the `devcontainer.json` instead!\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Docker-in-Docker\n\nSee the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/docker.md) for information on running Docker containers inside a devcontainer built by Envbuilder.\n\n## Caching\n\nTo speed up your builds, you can use a container registry as a cache.\nWhen creating the template, set the parameter `cache_repo` to a valid Docker repository.\n\nFor example, you can run a local registry:\n\n```shell\ndocker run --detach \\\n  --volume registry-cache:/var/lib/registry \\\n  --publish 5000:5000 \\\n  --name registry-cache \\\n  --net=host \\\n  registry:2\n```\n\nThen, when creating the template, enter `localhost:5000/devcontainer-cache` for the parameter `cache_repo`.\n\nSee the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.\n\n\u003e [!NOTE]\n\u003e We recommend using a registry cache with authentication enabled.\n\u003e To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path`\n\u003e with the path to a Docker config `.json` on disk containing valid credentials for the registry.\n"
+		"markdown": "\n# Remote Development on Docker Containers (with Envbuilder)\n\nProvision Envbuilder containers based on `devcontainer.json` as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.\n\n## Prerequisites\n\n### Infrastructure\n\nCoder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:\n\n```shell\n# Add coder user to Docker group\nsudo usermod -aG docker coder\n\n# Restart Coder server\nsudo systemctl restart coder\n\n# Test Docker\nsudo -u coder docker ps\n```\n\n## Architecture\n\nCoder supports Envbuilder containers based on `devcontainer.json` via [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/templates/dev-containers).\n\nThis template provisions the following resources:\n\n- Envbuilder cached image (conditional, persistent) using [`terraform-provider-envbuilder`](https://github.com/coder/terraform-provider-envbuilder)\n- Docker image (persistent) using [`envbuilder`](https://github.com/coder/envbuilder)\n- Docker container (ephemeral)\n- Docker volume (persistent on `/workspaces`)\n\nThe Git repository is cloned inside the `/workspaces` volume if not present.\nAny local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.\nKeep in mind that any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.\nEdit the `devcontainer.json` instead!\n\n\u003e **Note**\n\u003e This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.\n\n## Docker-in-Docker\n\nSee the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/docker.md) for information on running Docker containers inside an Envbuilder container.\n\n## Caching\n\nTo speed up your builds, you can use a container registry as a cache.\nWhen creating the template, set the parameter `cache_repo` to a valid Docker repository.\n\nFor example, you can run a local registry:\n\n```shell\ndocker run --detach \\\n  --volume registry-cache:/var/lib/registry \\\n  --publish 5000:5000 \\\n  --name registry-cache \\\n  --net=host \\\n  registry:2\n```\n\nThen, when creating the template, enter `localhost:5000/envbuilder-cache` for the parameter `cache_repo`.\n\nSee the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.\n\n\u003e [!NOTE]\n\u003e We recommend using a registry cache with authentication enabled.\n\u003e To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path`\n\u003e with the path to a Docker config `.json` on disk containing valid credentials for the registry.\n"
 	},
 	{
 		"id": "gcp-devcontainer",

diff --git a/examples/examples.go b/examples/examples.go
@@ -31,6 +31,7 @@ var (
 	//go:embed templates/digitalocean-linux
 	//go:embed templates/docker
 	//go:embed templates/docker-devcontainer
+	//go:embed templates/docker-envbuilder
 	//go:embed templates/gcp-devcontainer
 	//go:embed templates/gcp-linux
 	//go:embed templates/gcp-vm-container

diff --git a/examples/templates/docker-devcontainer/README.md b/examples/templates/docker-devcontainer/README.md
@@ -1,25 +1,27 @@
 ---
-display_name: Docker (Devcontainer)
-description: Provision envbuilder containers as Coder workspaces
+display_name: Docker-in-Docker Dev Containers
+description: Provision Docker containers as Coder workspaces running Dev Containers via Docker-in-Docker.
 icon: ../../../site/static/icon/docker.png
 maintainer_github: coder
 verified: true
-tags: [container, docker, devcontainer]
+tags: [docker, container, devcontainer]
 ---
 
-# Remote Development on Docker Containers (with Devcontainers)
+# Remote Development on Dev Containers
 
-Provision Devcontainers as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.
+Provision Docker containers as [Coder workspaces](https://coder.com/docs/workspaces) running [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) via Docker-in-Docker.
+
+<!-- TODO: Add screenshot -->
 
 ## Prerequisites
 
 ### Infrastructure
 
-Coder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:
+The VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:
 
-```shell
+```sh
 # Add coder user to Docker group
-sudo usermod -aG docker coder
+sudo adduser coder docker
 
 # Restart Coder server
 sudo systemctl restart coder
@@ -30,48 +32,18 @@ sudo -u coder docker ps
 
 ## Architecture
 
-Coder supports Devcontainers via [envbuilder](https://github.com/coder/envbuilder), an open source project. Read more about this in [Coder's documentation](https://coder.com/docs/templates/dev-containers).
+This example uses the `codercom/enterprise-node:ubuntu` Docker image as a base image for the workspace. It includes necessary tools like Docker and Node.js, which are required for running Dev Containers via the `@devcontainers/cli` tool.
 
 This template provisions the following resources:
 
-- Envbuilder cached image (conditional, persistent) using [`terraform-provider-envbuilder`](https://github.com/coder/terraform-provider-envbuilder)
-- Docker image (persistent) using [`envbuilder`](https://github.com/coder/envbuilder)
+- Docker image (built by Docker socket and kept locally)
 - Docker container (ephemeral)
-- Docker volume (persistent on `/workspaces`)
+- Docker volume (persistent on `/home/coder`)
+- Docker volume (persistent on `/var/lib/docker`)
+
+This means, when the workspace restarts, any tools or files outside of the home directory or docker library are not persisted.
 
-The Git repository is cloned inside the `/workspaces` volume if not present.
-Any local changes to the Devcontainer files inside the volume will be applied when you restart the workspace.
-Keep in mind that any tools or files outside of `/workspaces` or not added as part of the Devcontainer specification are not persisted.
-Edit the `devcontainer.json` instead!
+For devcontainers running inside the workspace, data persistence is dependent on each projects `devcontainer.json` configuration.
 
 > **Note**
 > This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
-
-## Docker-in-Docker
-
-See the [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/docker.md) for information on running Docker containers inside a devcontainer built by Envbuilder.
-
-## Caching
-
-To speed up your builds, you can use a container registry as a cache.
-When creating the template, set the parameter `cache_repo` to a valid Docker repository.
-
-For example, you can run a local registry:
-
-```shell
-docker run --detach \
-  --volume registry-cache:/var/lib/registry \
-  --publish 5000:5000 \
-  --name registry-cache \
-  --net=host \
-  registry:2
-```
-
-Then, when creating the template, enter `localhost:5000/devcontainer-cache` for the parameter `cache_repo`.
-
-See the [Envbuilder Terraform Provider Examples](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf/) for a more complete example of how the provider works.
-
-> [!NOTE]
-> We recommend using a registry cache with authentication enabled.
-> To allow Envbuilder to authenticate with the registry cache, specify the variable `cache_repo_docker_config_path`
-> with the path to a Docker config `.json` on disk containing valid credentials for the registry.