edit envbuilder docs

EdwardAngert · EdwardAngert · commit bff7a379860c · 2025-07-16T19:09:06.000Z
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -1,16 +1,16 @@
-# Dev container security and caching
+# Envbuilder Dev Container Security and Caching
 
-Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
-it with your existing HTTP proxies, firewalls, and artifact managers.
+Envbuilder can pull only pre-approved images and artifacts when you configure it with your enterprise proxies,
+firewalls, and artifact managers.
 
-## Configure registry authentication
+## Configure Registry Authentication
 
 You may need to authenticate to your container registry, such as Artifactory, or
 Git provider such as GitLab, to use Envbuilder. See the
 [Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md)
 for more information.
 
-## Layer and image caching
+## Layer and Image Caching
 
 To improve build times, dev containers can be cached. There are two main forms
 of caching:
@@ -60,7 +60,7 @@ If you are building your own Dev container template, you can consult the
 You may also wish to consult a
 [documented example usage of the `envbuilder_cached_image` resource](https://github.com/coder/terraform-provider-envbuilder/blob/main/examples/resources/envbuilder_cached_image/envbuilder_cached_image_resource.tf).
 
-## Next steps
+## Next Steps
 
 - [Dev container releases and known issues](./devcontainer-releases-known-issues.md)
 - [Dotfiles](../../../../user-guides/workspace-dotfiles.md)
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -1,4 +1,4 @@
-# Dev containers
+# Envbuilder Dev Containers
 
 A Development Container is an
 [open-source specification](https://containers.dev/implementors/spec/) for
@@ -14,91 +14,18 @@ pre-approved by platform teams in registries like
 workflows, reduces the need for tickets and approvals, and promotes greater
 independence for developers.
 
-## Prerequisites
-
-An administrator should construct or choose a base image and create a template
-that includes a `devcontainer_builder` image before a developer team configures
-dev containers.
-
-## Benefits of devcontainers
-
-There are several benefits to adding a dev container-compatible template to
-Coder:
-
-- Reliability through standardization
-- Scalability for growing teams
-- Improved security
-- Performance efficiency
-- Cost Optimization
-
-### Reliability through standardization
-
-Use dev containers to empower development teams to personalize their own
-environments while maintaining consistency and security through an approved and
-hardened base image.
-
-Standardized environments ensure uniform behavior across machines and team
-members, eliminating "it works on my machine" issues and creating a stable
-foundation for development and testing. Containerized setups reduce dependency
-conflicts and misconfigurations, enhancing build stability.
-
-### Scalability for growing teams
-
-Dev containers allow organizations to handle multiple projects and teams
-efficiently.
-
-You can leverage platforms like Kubernetes to allocate resources on demand,
-optimizing costs and ensuring fair distribution of quotas. Developer teams can
-use efficient custom images and independently configure the contents of their
-version-controlled dev containers.
+Envbuilder is a legacy implementation of dev containers.
 
-This approach allows organizations to scale seamlessly, reducing the maintenance
-burden on the administrators that support diverse projects while allowing
-development teams to maintain their own images and onboard new users quickly.
+For the Docker-based Dev Containers integration, follow the [Configure a template for dev containers](../../extending-templates/devcontainers.md) documentation instead.
 
-### Improved security
-
-Since Coder and Envbuilder run on your own infrastructure, you can use firewalls
-and cluster-level policies to ensure Envbuilder only downloads packages from
-your secure registry powered by JFrog Artifactory or Sonatype Nexus.
-Additionally, Envbuilder can be configured to push the full image back to your
-registry for additional security scanning.
-
-This means that Coder admins can require hardened base images and packages,
-while still allowing developer self-service.
-
-Envbuilder runs inside a small container image but does not require a Docker
-daemon in order to build a dev container. This is useful in environments where
-you may not have access to a Docker socket for security reasons, but still need
-to work with a container.
-
-### Performance efficiency
-
-Create a unique image for each project to reduce the dependency size of any
-given project.
-
-Envbuilder has various caching modes to ensure workspaces start as fast as
-possible, such as layer caching and even full image caching and fetching via the
-[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs).
-
-### Cost optimization
-
-By creating unique images per-project, you remove unnecessary dependencies and
-reduce the workspace size and resource consumption of any given project. Full
-image caching ensures optimal start and stop times.
-
-## When to use a dev container
+## Prerequisites
 
-Dev containers are a good fit for developer teams who are familiar with Docker
-and are already using containerized development environments. If you have a
-large number of projects with different toolchains, dependencies, or that depend
-on a particular Linux distribution, dev containers make it easier to quickly
-switch between projects.
+An administrator should construct or choose a base image and create a template
+that includes an Envbuilder container image `coder/envbuilder` before a developer team configures dev containers.
 
-They may also be a great fit for more restricted environments where you may not
-have access to a Docker daemon since it doesn't need one to work.
+Compare the differences between [Envbuilder and the Dev Containers integration](../../extending-templates/dev-containers-envbuilder.md).
 
-## Devcontainer Features
+## Dev Container Features
 
 [Dev container Features](https://containers.dev/implementors/features/) allow
 owners of a project to specify self-contained units of code and runtime
@@ -119,4 +46,5 @@ of the Coder control plane and even run within a CI/CD pipeline.
 
 ## Next steps
 
-- [Add a dev container template](./add-devcontainer.md)
+- [Add an Envbuilder dev container template](./add-devcontainer.md)
+- [Choose an approach to Dev Containers](../../extending-templates/dev-containers-envbuilder.md)
