docs: describe devcontainers as deployment model (#12877)

mtojek · web-flow · commit 7c0fac990644 · 2024-04-05T15:30:49.000+02:00
diff --git a/docs/about/architecture.md b/docs/about/architecture.md
@@ -268,3 +268,54 @@ Coder on Kubernetes.
   [Microsoft Entra ID Sign-On](https://learn.microsoft.com/en-us/entra/identity/app-proxy/)
 - For GCP:
   [Google Cloud Identity Platform](https://cloud.google.com/architecture/identity/single-sign-on)
+
+### Dev Container
+
+Note: _Dev containers_ are at early stage and considered experimental at the
+moment.
+
+This architecture enhances a Coder workspace with a
+[development container](https://containers.dev/) setup built using the
+[envbuilder](https://github.com/coder/envbuilder) project. Workspace users have
+the flexibility to extend generic, base developer environments with custom,
+project-oriented [features](https://containers.dev/features) without requiring
+platform administrators to push altered Docker images.
+
+Learn more about
+[Dev containers support](https://coder.com/docs/v2/latest/templates/devcontainers)
+in Coder.
+
+![Architecture Diagram](../images/architecture-devcontainers.png)
+
+#### Components
+
+The deployment model includes:
+
+- _Workspace_ built using Coder template with _envbuilder_ enabled to set up the
+  developer environment accordingly to the dev container spec.
+- _Container Registry_ for Docker images used by _envbuilder_, maintained by
+  Coder platform engineers or developer productivity engineers.
+
+Since this model is strictly focused on workspace nodes, it does not affect the
+setup of regional infrastructure. It can be deployed alongside other deployment
+models, in multiple regions, or across various cloud platforms.
+
+##### Workload resources
+
+**Workspace**
+
+- Docker and Kubernetes based templates are supported.
+- The `docker_container` resource uses `ghcr.io/coder/envbuilder` as the base
+  image.
+
+_Envbuilder_ checks out the base Docker image from the container registry and
+installs selected features as specified in the `devcontainer.json` on top.
+Eventually, it starts the container with the developer environment.
+
+##### Workload supporting resources
+
+**Container Registry (optional)**
+
+- Workspace nodes need access to the Container Registry to check out images. To
+  shorten the provisioning time, it is recommended to deploy registry mirrors in
+  the same region as the workspace nodes.
diff --git a/docs/images/architecture-devcontainers.png b/docs/images/architecture-devcontainers.png
diff --git a/docs/templates/devcontainers.md b/docs/templates/devcontainers.md
@@ -1,17 +1,17 @@
-# Devcontainers (alpha)
+# Dev Containers (alpha)
 
-[Devcontainers](https://containers.dev) are an open source specification for
-defining development environments.
+[Development containers](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
+Coder that runs dev containers via Coder templates and your underlying
 infrastructure. It can run on Docker or Kubernetes.
 
 There are several benefits to adding a devcontainer-compatible template to
 Coder:
 
-- Drop-in migration from Codespaces (or any existing repositories that use
-  devcontainers)
+- Drop-in migration from Codespaces (or any existing repositories that use dev
+  containers)
 - Easier to start projects from Coder. Just create a new workspace then pick a
   starter devcontainer.
 - Developer teams can "bring their own image." No need for platform teams to
@@ -47,7 +47,7 @@ information.
 
 ## Caching
 
-To improve build times, devcontainers can be cached. Refer to the
+To improve build times, dev containers can be cached. Refer to the
 [envbuilder documentation](https://github.com/coder/envbuilder/) for more
 information.
 
