coder · johnstcn · Jul 22, 2024 · Jul 5, 2024 · Jul 5, 2024 · Jul 5, 2024
diff --git a/examples/templates/devcontainer-docker/README.md b/examples/templates/devcontainer-docker/README.md
@@ -9,19 +9,17 @@ tags: [container, docker, devcontainer]
 
 # Remote Development on Docker Containers (with Devcontainers)
 
-Provision Docker containers as [Coder workspaces](https://coder.com/docs/workspaces) with this example template.
-
-<!-- TODO: Add screenshot -->
+Provision Devcontainers as [Coder workspaces](https://coder.com/docs/workspaces) in Docker with this example template.
 
 ## Prerequisites
 
 ### Infrastructure
 
-The VM you run Coder on must have a running Docker socket and the `coder` user must be added to the Docker group:
+Coder must have access to a running Docker socket, and the `coder` user must be a member of the `docker` group:
 
-```sh
+```shell
 # Add coder user to Docker group
-sudo adduser coder docker
+sudo usermod -aG docker coder
 
 # Restart Coder server
 sudo systemctl restart coder
@@ -32,19 +30,45 @@ sudo -u coder docker ps
 
 ## Architecture
 
-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/templates/dev-containers).
+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 template provisions the following resources:
 
-- Docker image (built by Docker socket and kept locally)
-- Docker container pod (ephemeral)
-- Docker volume (persistent on `/home/coder`)
+- Docker image (persistent)
+- Docker container (ephemeral)
+- Docker volume (persistent on `/workspaces`)
 
-This means, when the workspace restarts, any tools or files outside of the home directory are not persisted. To pre-bake tools into the workspace (e.g. `python3`), modify the container image. Alternatively, individual developers can [personalize](https://coder.com/docs/dotfiles) their workspaces with dotfiles.
+with [`envbuilder`](https://github.com/coder/envbuilder).
+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!
 
 > **Note**
 > This template is designed to be a starting point! Edit the Terraform to extend the template to support your use case.
 
-### Editing the image
+## 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`.
+
+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`.
 
-Edit the `Dockerfile` and run `coder templates push` to update workspaces.
+> [!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.