From d741460e4437682d1039fcdca3473f896c7dbe65 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 8 Nov 2024 17:48:43 +0000
Subject: [PATCH 01/36] add definitions to admin/index
---
docs/admin/index.md | 16 ++++++++++++++++
1 file changed, 16 insertions(+)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 6ef0e6fb6541a..572f21a794264 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -15,4 +15,20 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
+## What is an image, template, devcontainer, or workspace
+
+<dl>
+ <dt>Image</dt>
+ <dd>this is an image</dd>
+
+ <dt>Template</dt>
+ <dd>about templates</dd>
+
+ <dt>Development containers</dt>
+ <dd>more about devcontainers</dd>
+
+ <dt>Workspace</dt>
+ <dd>iykyk</dd>
+</dl>
+
<children></children>
From 3ed5c3e57b91727ee242c50738ba24fd82cfc81a Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 8 Nov 2024 19:43:08 +0000
Subject: [PATCH 02/36] init devcontainers best practice doc
---
docs/admin/index.md | 14 +-
.../managing-templates/devcontainers.md | 217 +++++++++++++-----
.../managing-templates/image-management.md | 2 +-
docs/manifest.json | 2 +-
4 files changed, 166 insertions(+), 69 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 572f21a794264..8bab26cd589b1 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -18,17 +18,17 @@ For any information not strictly contained in these sections, check out our
## What is an image, template, devcontainer, or workspace
<dl>
- <dt>Image</dt>
- <dd>this is an image</dd>
-
<dt>Template</dt>
- <dd>about templates</dd>
+ <dd>[Templates](./templates/index.md) are </dd>
+
+ <dt>Workspace</dt>
+ <dd>A [workspace](../user-guides/workspace-management.md) is the environment that a developer works in. Developers on a team each work from their own workspace and can use [multiple IDEs](./workspace-access/index.md).</dd>
+
+ <dt>Image</dt>
+ <dd>An [image](./templates/managing-templates/image-management.md) contains the utilities that the Coder workspace is built on. It can be an [example image](https://github.com/coder/images), custom image, or one from [Docker Hub](https://hub.docker.com/search). It is defined in each template.</dd>
<dt>Development containers</dt>
<dd>more about devcontainers</dd>
-
- <dt>Workspace</dt>
- <dd>iykyk</dd>
</dl>
<children></children>
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
index 088f733adceb3..fbd5fa7a5fb34 100644
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ b/docs/admin/templates/managing-templates/devcontainers.md
@@ -1,56 +1,144 @@
-# Dev Containers
+# Development containers on Coder
-[Development containers](https://containers.dev) are an open source
-specification for defining development environments.
+A development container is an
+[open source specification](https://containers.dev/implementors/spec/) for
+defining containerized development environments.
-[Envbuilder](https://github.com/coder/envbuilder) is an open source project by
-Coder that runs dev containers via Coder templates and your underlying
-infrastructure. It can run on Docker or Kubernetes.
+Leverage Coder with dev containers and apply cloud-native security practices to
+traditional ticket-ops and approval-ops workflows to help enable developers to
+self-service.
There are several benefits to adding a devcontainer-compatible template to
Coder:
-- 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
- manage complex images, registries, and CI pipelines.
+- Reliability and scalability
+- Improved security
+- Performance efficiency
+- Cost Optimization
-## How it works
+## Benefits of devcontainers
-A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
-Then developers enter their repository URL as a
-[parameter](../extending-templates/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.
+### Reliability and scalability
-When using the [Envbuilder Terraform provider](#envbuilder-terraform-provider),
-a previously built and cached image can be re-used directly, allowing
-instantaneous dev container starts.
+Envbuilder is an open source project independently packaged and versioned from
+the centralized Coder open source project. This means that it can be used with
+Coder, but it is not required. It also means that Dev Container builds can scale
+independently of the Coder control plane and even run in CI/CD.
+
+### 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 still require hardened base images and
+packages, while still allowing developer self service.
+
+### 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.
+
+## Coder Envbuilder
+
+Envbuilder is an open source project by Coder that runs dev containers via Coder
+templates and your underlying infrastructure. It can run on Docker or
+Kubernetes.
+
+Envbuilder uses the Dev Container standard used in VS Code Local, Daytona,
+DevPod, and Codespaces. This format is already familiar to developers and can
+simplify migration. This allows developers to take control of their own
+environments, while still following cloud-native security best practices. See
+the [Security section](#devcontainer-security) for more information.
+
+## Add a devcontainer template to Coder
+
+A Coder admin adds a devcontainer-compatible template to Coder (Envbuilder).
+
+When a developer creates their workspace, they enter their repository URL as a
+[parameter](../extending-templates/parameters.md). 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.
+Admin:
+
+1. Use a [devcontainer template](https://registry.coder.com/templates)
+1. Create a template with the template files from the registry (git clone,
+ upload files, or copy paste)
+1. In template settings > variables > set necessary variables such as the
+ namespace
+1. Create a workspace from the template
+1. Choose a **Repository** URL
+ - The repo must have a `.devcontainer` directory with `devcontainer.json`
+
+When using the [Envbuilder Terraform provider](#envbuilder-terraform-provider),
+a previously built and cached image can be reused directly, allowing dev
+containers to start instantaneously.
+
+Developers can edit the `devcontainer.json` in their workspace to customize
+their development environments:
+
+```json
+…
+"customizations": {
+ // Configure properties specific to VS Code.
+ "vscode": {
+ "settings": {
+ "editor.tabSize": 4,
+ "editor.detectIndentation": false
+ "editor.insertSpaces": true
+ "files.trimTrailingWhitespace": true
+ },
+ "extensions": [
+ "github.vscode-pull-request-github",
+ ]
+ }
+},
+…
+```
## Example templates
-- [Devcontainers (Docker)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- provisions a development container using Docker.
-- [Devcontainers (Kubernetes)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- provisions a development container on the Kubernetes.
-- [Google Compute Engine (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
- runs a development container inside a single GCP instance. It also mounts the
- Docker socket from the VM inside the container to enable Docker inside the
- workspace.
-- [AWS EC2 (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
- runs a development container inside a single EC2 instance. It also mounts the
- Docker socket from the VM inside the container to enable Docker inside the
- workspace.
+- [Docker devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
+ - Docker provisions a development container.
+- [Kubernetes devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
+ - Provisions a development container on the Kubernetes.
+- [Google Compute Engine devcontainer](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
+ - Runs a development container inside a single GCP instance. It also mounts
+ the Docker socket from the VM inside the container to enable Docker inside
+ the workspace.
+- [AWS EC2 devcontainer](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
+ - Runs a development container inside a single EC2 instance. It also mounts
+ the Docker socket from the VM inside the container to enable Docker inside
+ the workspace.
+
+Your template can prompt the user for a repo URL with
+[parameters](../extending-templates/parameters.md):
-Your template can prompt the user for a repo URL with
-[Parameters](../extending-templates/parameters.md).
+## Devcontainer security
+
+Ensure Envbuilder can only pull images and artifacts by configuring it with your
+existing HTTP proxies, firewalls, and artifact managers.
+
+### 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.
## Authentication
@@ -59,54 +147,63 @@ 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.
-## Caching
+## Layer and image caching
To improve build times, dev containers can be cached. There are two main forms
of caching:
-1. **Layer Caching** caches individual layers and pushes them to a remote
- registry. When building the image, Envbuilder will check the remote registry
- for pre-existing layers. These will be fetched and extracted to disk instead
- of building the layers from scratch.
-2. **Image Caching** caches the _entire image_, skipping the build process
- completely (except for post-build lifecycle scripts).
+<dl>
+ <dt>Layer caching</dt>
+ <dd>Caches individual layers and pushes them to a remote registry. When building the image, Envbuilder will check the remote registry for pre-existing layers These will be fetched and extracted to disk instead of building the layers from scratch.</dd>
+ <dt>Image caching</dt>
+ <dd>Caches the entire image, skipping the build process completely (except for post-build lifecycle scripts).</dd>
+</dl>
Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
for more information.
-## Envbuilder Terraform Provider
+### Image caching
To support resuming from a cached image, use the
[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
in your template. The provider will:
1. Clone the remote Git repository,
-2. Perform a 'dry-run' build of the dev container in the same manner as
+1. Perform a 'dry-run' build of the dev container in the same manner as
Envbuilder would,
-3. Check for the presence of a previously built image in the provided cache
+1. Check for the presence of a previously built image in the provided cache
repository,
-4. Output the image remote reference in SHA256 form, if found.
+1. Output the image remote reference in SHA256 form, if it finds one.
-The above example templates will use the provider if a remote cache repository
-is provided.
+The example templates listed above will use the provider if a remote cache
+repository is provided.
If you are building your own Devcontainer template, you can consult the
[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
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).
-## Other features & known issues
+## Release channels
Envbuilder provides two release channels:
-- **Stable:** available at
- [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
- Tags `>=1.0.0` are considered stable.
-- **Preview:** available at
- [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
- This is built from the tip of `main`, and should be considered
- **experimental** and prone to **breaking changes**.
+- **Stable**
+ - Available at
+ [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
+ Tags `>=1.0.0` are considered stable.
+- **Preview**
+ - Available at
+ [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
+ Built from the tip of `main`, and should be considered experimental and
+ prone to breaking changes.
+
+Refer to the
+[Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more
+information and to submit feature requests or bug reports.
+
+## Known issues
-Refer to the [Envbuilder GitHub repo](https://github.com/coder/envbuilder/) for
-more information and to submit feature requests or bug reports.
+Visit the
+[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
+for a full list of supported features and known issues.
diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md
index e1536be3f0adb..cfb9880f0f53a 100644
--- a/docs/admin/templates/managing-templates/image-management.md
+++ b/docs/admin/templates/managing-templates/image-management.md
@@ -13,7 +13,7 @@ practices around managing workspaces images for Coder.
> Note: An image is just one of the many properties defined within the template.
> Templates can pull images from a public image registry (e.g. Docker Hub) or an
-> internal one., thanks to Terraform.
+> internal one, thanks to Terraform.
## Create a minimal base image
diff --git a/docs/manifest.json b/docs/manifest.json
index 8a8cc6c771794..9e13d24cc58e8 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -321,7 +321,7 @@
"path": "./admin/templates/managing-templates/change-management.md"
},
{
- "title": "Devcontainers",
+ "title": "Development containers on Coder",
"description": "Learn about using devcontainers in templates",
"path": "./admin/templates/managing-templates/devcontainers.md"
},
From dcf901c2127f4fb751e4b0949ba88426eb185eb6 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 8 Nov 2024 20:00:24 +0000
Subject: [PATCH 03/36] s/definition list/bullets
---
docs/admin/index.md | 26 +++++++++----------
.../managing-templates/devcontainers.md | 3 ++-
2 files changed, 15 insertions(+), 14 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 8bab26cd589b1..5f4769acff063 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -17,18 +17,18 @@ For any information not strictly contained in these sections, check out our
## What is an image, template, devcontainer, or workspace
-<dl>
- <dt>Template</dt>
- <dd>[Templates](./templates/index.md) are </dd>
-
- <dt>Workspace</dt>
- <dd>A [workspace](../user-guides/workspace-management.md) is the environment that a developer works in. Developers on a team each work from their own workspace and can use [multiple IDEs](./workspace-access/index.md).</dd>
-
- <dt>Image</dt>
- <dd>An [image](./templates/managing-templates/image-management.md) contains the utilities that the Coder workspace is built on. It can be an [example image](https://github.com/coder/images), custom image, or one from [Docker Hub](https://hub.docker.com/search). It is defined in each template.</dd>
-
- <dt>Development containers</dt>
- <dd>more about devcontainers</dd>
-</dl>
+- **Template**
+ - [Templates](./templates/index.md) are...
+- **Workspace**
+ - A [workspace](../user-guides/workspace-management.md) is the environment
+ that a developer works in. Developers on a team each work from their own
+ workspace and can use [multiple IDEs](./workspace-access/index.md).
+- **Image**
+ - An [image](./templates/managing-templates/image-management.md) contains the
+ utilities that the Coder workspace is built on. It can be an
+ [example image](https://github.com/coder/images), custom image, or one from
+ [Docker Hub](https://hub.docker.com/search). It is defined in each template.
+- **Development containers**
+ - more about devcontainers...
<children></children>
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
index fbd5fa7a5fb34..2d0f316146d52 100644
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ b/docs/admin/templates/managing-templates/devcontainers.md
@@ -82,7 +82,8 @@ Admin:
1. Choose a **Repository** URL
- The repo must have a `.devcontainer` directory with `devcontainer.json`
-When using the [Envbuilder Terraform provider](#envbuilder-terraform-provider),
+When using the
+[Envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder),
a previously built and cached image can be reused directly, allowing dev
containers to start instantaneously.
From e96b1bc70036c9827a5a40c070e4bf1246a852e9 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 14:06:26 +0000
Subject: [PATCH 04/36] admin/index glossary section
---
docs/admin/index.md | 12 ++++++++++--
1 file changed, 10 insertions(+), 2 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 5f4769acff063..0e831715e2f66 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -18,17 +18,25 @@ For any information not strictly contained in these sections, check out our
## What is an image, template, devcontainer, or workspace
- **Template**
- - [Templates](./templates/index.md) are...
+ - [Templates](./templates/index.md) are
+ <!-- Managed by Coder Template Administrators The template should include infrastructure-level dependencies for the workspace (for example, Kubernetes PersistentVolumeClaims, docker containers, or EC2 VMs). These should be applicable to all workspaces built from the template. -->
+
- **Workspace**
- A [workspace](../user-guides/workspace-management.md) is the environment
that a developer works in. Developers on a team each work from their own
workspace and can use [multiple IDEs](./workspace-access/index.md).
- **Image**
- - An [image](./templates/managing-templates/image-management.md) contains the
+ - A [base image](./templates/managing-templates/image-management.md) contains the
utilities that the Coder workspace is built on. It can be an
[example image](https://github.com/coder/images), custom image, or one from
[Docker Hub](https://hub.docker.com/search). It is defined in each template.
+ Managed externally to Coder.
+ <!-- The devcontainer base image should include dependencies such as the base OS (for example, Debian or Fedora), and OS-level packages (curl, git, java). Include as much as possible here to leverage image and layer caching. Avoid including project-specific tools here. Language-specific runtimes may be added here or in a Dev Container feature. -->
+
- **Development containers**
- more about devcontainers...
+- **Startup scripts**
+ -
+
<children></children>
From 22e399dd055c7b6e5555b1ff393f1e34ec5e3f3d Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 15:30:30 +0000
Subject: [PATCH 05/36] when to use a dev container
---
.../templates/managing-templates/devcontainers.md | 10 +++++++---
1 file changed, 7 insertions(+), 3 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
index 2d0f316146d52..2c0bd44464150 100644
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ b/docs/admin/templates/managing-templates/devcontainers.md
@@ -1,6 +1,6 @@
# Development containers on Coder
-A development container is an
+A development container (dev container or devcontainer) is an
[open source specification](https://containers.dev/implementors/spec/) for
defining containerized development environments.
@@ -8,6 +8,8 @@ Leverage Coder with dev containers and apply cloud-native security practices to
traditional ticket-ops and approval-ops workflows to help enable developers to
self-service.
+## Benefits of devcontainers
+
There are several benefits to adding a devcontainer-compatible template to
Coder:
@@ -16,8 +18,6 @@ Coder:
- Performance efficiency
- Cost Optimization
-## Benefits of devcontainers
-
### Reliability and scalability
Envbuilder is an open source project independently packaged and versioned from
@@ -51,6 +51,10 @@ 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
+
+A development container
+
## Coder Envbuilder
Envbuilder is an open source project by Coder that runs dev containers via Coder
From 8e37e58455f79b4fdfd345342d14ed1686447808 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 19:17:55 +0000
Subject: [PATCH 06/36] admin/index glossary; devcontainer known issues
---
docs/admin/index.md | 48 ++++++++++++++-----
.../managing-templates/devcontainers.md | 27 ++++++++++-
2 files changed, 62 insertions(+), 13 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 0e831715e2f66..26e429de83ae9 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -17,26 +17,50 @@ For any information not strictly contained in these sections, check out our
## What is an image, template, devcontainer, or workspace
+- **Image**
+
+ - A [base image](./templates/managing-templates/image-management.md) contains
+ the operating system (OS), OS-level packages, and utilities that the Coder
+ workspace is built on. It can be an
+ [example image](https://github.com/coder/images), custom image, or one from
+ [Docker Hub](https://hub.docker.com/search). It is defined in each template.
+ - Managed by: Externally to Coder.
+
- **Template**
- - [Templates](./templates/index.md) are
- <!-- Managed by Coder Template Administrators The template should include infrastructure-level dependencies for the workspace (for example, Kubernetes PersistentVolumeClaims, docker containers, or EC2 VMs). These should be applicable to all workspaces built from the template. -->
+
+ - [Templates](./templates/index.md) include infrastructure-level dependencies
+ for the workspace. For example, a template can include Kubernetes
+ PersistentVolumeClaims, Docker containers, or EC2 VMs.
+ - Managed by: Template administrators from within the Coder deployment.
+
+- **Startup scripts**
+
+ - Agent startup scripts apply to all users of a template. This is an
+ intentionally flexible area that template authors have at their disposal to
+ manage the "last mile" of workspace creation.
+ - Managed by: Coder template administrators.
- **Workspace**
+
- A [workspace](../user-guides/workspace-management.md) is the environment
that a developer works in. Developers on a team each work from their own
- workspace and can use [multiple IDEs](./workspace-access/index.md).
-- **Image**
- - A [base image](./templates/managing-templates/image-management.md) contains the
- utilities that the Coder workspace is built on. It can be an
- [example image](https://github.com/coder/images), custom image, or one from
- [Docker Hub](https://hub.docker.com/search). It is defined in each template.
- Managed externally to Coder.
- <!-- The devcontainer base image should include dependencies such as the base OS (for example, Debian or Fedora), and OS-level packages (curl, git, java). Include as much as possible here to leverage image and layer caching. Avoid including project-specific tools here. Language-specific runtimes may be added here or in a Dev Container feature. -->
+ workspace and can use
+ [multiple IDEs](../user-guides/workspace-access/index.md).
+ - Managed by:
- **Development containers**
+
- more about devcontainers...
+ - Managed by:
-- **Startup scripts**
- -
+- **Dotfiles / personalization**
+
+ - Users may have their own specific preferences relating to shell prompt,
+ custom keybindings, color schemes, and more. Users can leverage Coder's
+ [dotfiles support](../user-guides/workspace-dotfiles.md) or create their own
+ script to personalize their workspace. Be aware that users with root
+ permissions in their workspace can override almost all of the previous
+ configuration.
+ - Managed by: User
<children></children>
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
index 2c0bd44464150..30e058d5f48e0 100644
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ b/docs/admin/templates/managing-templates/devcontainers.md
@@ -53,7 +53,7 @@ image caching ensures optimal start and stop times.
## When to use a dev container
-A development container
+A development container
## Coder Envbuilder
@@ -168,6 +168,8 @@ Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
for more information.
+Note that caching requires push access to a registry, and may require approval.
+
### Image caching
To support resuming from a cached image, use the
@@ -209,6 +211,29 @@ information and to submit feature requests or bug reports.
## Known issues
+- Image caching: error pushing image
+
+ - `BLOB_UNKNOWN: Manifest references unknown blob(s)`
+ - [Issue 385](https://github.com/coder/envbuilder/issues/385)
+
+- Support for VS Code Extensions requires a workaround.
+
+ - [Issue 68](https://github.com/coder/envbuilder/issues/68#issuecomment-1805974271)
+
+- Envbuilder does not support Volume Mounts
+
+- Support for lifecycle hooks is limited.
+ ([Issue](https://github.com/coder/envbuilder/issues/395))
+ - Supported:
+ - `onCreateCommand`
+ - `updateContentCommand`
+ - `postCreateCommand`
+ - `postStartCommand`
+ - Not supported:
+ - `initializeCommand`
+ - `postAttachCommand`
+ - `waitFor`
+
Visit the
[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
for a full list of supported features and known issues.
From 985233a7ccec7ba7cdba546db60262a0f29ac8bf Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 19:25:10 +0000
Subject: [PATCH 07/36] devcontainer lifecycle scripts
---
.../managing-templates/devcontainers.md | 33 +++++++++++++++----
1 file changed, 27 insertions(+), 6 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
index 30e058d5f48e0..0e40be5df43b6 100644
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ b/docs/admin/templates/managing-templates/devcontainers.md
@@ -67,6 +67,14 @@ simplify migration. This allows developers to take control of their own
environments, while still following cloud-native security best practices. See
the [Security section](#devcontainer-security) for more information.
+## Devcontainer Features
+
+[Devcontainer Features](https://containers.dev/implementors/features/) allow
+owners of a project to specify self-contained units of code and runtime
+configuration that can be composed together on top of an existing base image.
+This is a good place to install project-specific tools, such as
+language-specific runtimes and compilers.
+
## Add a devcontainer template to Coder
A Coder admin adds a devcontainer-compatible template to Coder (Envbuilder).
@@ -157,12 +165,16 @@ for more information.
To improve build times, dev containers can be cached. There are two main forms
of caching:
-<dl>
- <dt>Layer caching</dt>
- <dd>Caches individual layers and pushes them to a remote registry. When building the image, Envbuilder will check the remote registry for pre-existing layers These will be fetched and extracted to disk instead of building the layers from scratch.</dd>
- <dt>Image caching</dt>
- <dd>Caches the entire image, skipping the build process completely (except for post-build lifecycle scripts).</dd>
-</dl>
+- **Layer caching**
+
+ - Caches individual layers and pushes them to a remote registry. When building
+ the image, Envbuilder will check the remote registry for pre-existing layers
+ These will be fetched and extracted to disk instead of building the layers
+ from scratch.
+
+- **Image caching**
+ - Caches the entire image, skipping the build process completely (except for
+ post-build [lifecycle scripts](#devcontainer-lifecycle-scripts)).
Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
@@ -191,6 +203,15 @@ If you are building your own Devcontainer 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).
+## Devcontainer lifecycle scripts
+
+The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
+`postStartCommand` lifecycle scripts are run each time the container is started.
+This could be used, for example, to fetch or update project dependencies before
+a user begins using the workspace.
+
+Lifecycle scripts are managed by project developers.
+
## Release channels
Envbuilder provides two release channels:
From f2c59beeed8553e457b954b3bc0adb519ade9092 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 20:10:57 +0000
Subject: [PATCH 08/36] devcontainers directory
---
docs/admin/templates/index.md | 5 +-
.../managing-templates/devcontainers.md | 260 ------------------
.../devcontainers/add-devcontainer.md | 79 ++++++
.../devcontainer-releases-known-issues.md | 48 ++++
.../devcontainer-security-caching.md | 67 +++++
.../managing-templates/devcontainers/index.md | 82 ++++++
.../managing-templates/image-management.md | 2 +-
.../templates/managing-templates/index.md | 2 +-
docs/manifest.json | 19 +-
9 files changed, 299 insertions(+), 265 deletions(-)
delete mode 100644 docs/admin/templates/managing-templates/devcontainers.md
create mode 100644 docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
create mode 100644 docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
create mode 100644 docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
create mode 100644 docs/admin/templates/managing-templates/devcontainers/index.md
diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md
index ad9c3ef965592..de8ab2cddaecc 100644
--- a/docs/admin/templates/index.md
+++ b/docs/admin/templates/index.md
@@ -48,8 +48,9 @@ needs of different teams.
- [Image management](./managing-templates/image-management.md): Learn how to
create and publish images for use within Coder workspaces & templates.
-- [Dev Container support](./managing-templates/devcontainers.md): Enable dev
- containers to allow teams to bring their own tools into Coder workspaces.
+- [Dev Container support](./managing-templates/devcontainers/index.md.md):
+ Enable dev containers to allow teams to bring their own tools into Coder
+ workspaces.
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
Configure your template to prevent certain resources from being destroyed
(e.g. user disks).
diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md
deleted file mode 100644
index 0e40be5df43b6..0000000000000
--- a/docs/admin/templates/managing-templates/devcontainers.md
+++ /dev/null
@@ -1,260 +0,0 @@
-# Development containers on Coder
-
-A development container (dev container or devcontainer) is an
-[open source specification](https://containers.dev/implementors/spec/) for
-defining containerized development environments.
-
-Leverage Coder with dev containers and apply cloud-native security practices to
-traditional ticket-ops and approval-ops workflows to help enable developers to
-self-service.
-
-## Benefits of devcontainers
-
-There are several benefits to adding a devcontainer-compatible template to
-Coder:
-
-- Reliability and scalability
-- Improved security
-- Performance efficiency
-- Cost Optimization
-
-### Reliability and scalability
-
-Envbuilder is an open source project independently packaged and versioned from
-the centralized Coder open source project. This means that it can be used with
-Coder, but it is not required. It also means that Dev Container builds can scale
-independently of the Coder control plane and even run in CI/CD.
-
-### 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 still require hardened base images and
-packages, while still allowing developer self service.
-
-### 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
-
-A development container
-
-## Coder Envbuilder
-
-Envbuilder is an open source project by Coder that runs dev containers via Coder
-templates and your underlying infrastructure. It can run on Docker or
-Kubernetes.
-
-Envbuilder uses the Dev Container standard used in VS Code Local, Daytona,
-DevPod, and Codespaces. This format is already familiar to developers and can
-simplify migration. This allows developers to take control of their own
-environments, while still following cloud-native security best practices. See
-the [Security section](#devcontainer-security) for more information.
-
-## Devcontainer Features
-
-[Devcontainer Features](https://containers.dev/implementors/features/) allow
-owners of a project to specify self-contained units of code and runtime
-configuration that can be composed together on top of an existing base image.
-This is a good place to install project-specific tools, such as
-language-specific runtimes and compilers.
-
-## Add a devcontainer template to Coder
-
-A Coder admin adds a devcontainer-compatible template to Coder (Envbuilder).
-
-When a developer creates their workspace, they enter their repository URL as a
-[parameter](../extending-templates/parameters.md). Envbuilder clones the repo
-and builds a container from the `devcontainer.json` specified in the repo.
-
-Admin:
-
-1. Use a [devcontainer template](https://registry.coder.com/templates)
-1. Create a template with the template files from the registry (git clone,
- upload files, or copy paste)
-1. In template settings > variables > set necessary variables such as the
- namespace
-1. Create a workspace from the template
-1. Choose a **Repository** URL
- - The repo must have a `.devcontainer` directory with `devcontainer.json`
-
-When using the
-[Envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder),
-a previously built and cached image can be reused directly, allowing dev
-containers to start instantaneously.
-
-Developers can edit the `devcontainer.json` in their workspace to customize
-their development environments:
-
-```json
-…
-"customizations": {
- // Configure properties specific to VS Code.
- "vscode": {
- "settings": {
- "editor.tabSize": 4,
- "editor.detectIndentation": false
- "editor.insertSpaces": true
- "files.trimTrailingWhitespace": true
- },
- "extensions": [
- "github.vscode-pull-request-github",
- ]
- }
-},
-…
-```
-
-## Example templates
-
-- [Docker devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- - Docker provisions a development container.
-- [Kubernetes devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- - Provisions a development container on the Kubernetes.
-- [Google Compute Engine devcontainer](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
- - Runs a development container inside a single GCP instance. It also mounts
- the Docker socket from the VM inside the container to enable Docker inside
- the workspace.
-- [AWS EC2 devcontainer](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
- - Runs a development container inside a single EC2 instance. It also mounts
- the Docker socket from the VM inside the container to enable Docker inside
- the workspace.
-
-Your template can prompt the user for a repo URL with
-[parameters](../extending-templates/parameters.md):
-
-
-
-## Devcontainer security
-
-Ensure Envbuilder can only pull images and artifacts by configuring it with your
-existing HTTP proxies, firewalls, and artifact managers.
-
-### 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.
-
-## 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
-
-To improve build times, dev containers can be cached. There are two main forms
-of caching:
-
-- **Layer caching**
-
- - Caches individual layers and pushes them to a remote registry. When building
- the image, Envbuilder will check the remote registry for pre-existing layers
- These will be fetched and extracted to disk instead of building the layers
- from scratch.
-
-- **Image caching**
- - Caches the entire image, skipping the build process completely (except for
- post-build [lifecycle scripts](#devcontainer-lifecycle-scripts)).
-
-Refer to the
-[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
-for more information.
-
-Note that caching requires push access to a registry, and may require approval.
-
-### Image caching
-
-To support resuming from a cached image, use the
-[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
-in your template. The provider will:
-
-1. Clone the remote Git repository,
-1. Perform a 'dry-run' build of the dev container in the same manner as
- Envbuilder would,
-1. Check for the presence of a previously built image in the provided cache
- repository,
-1. Output the image remote reference in SHA256 form, if it finds one.
-
-The example templates listed above will use the provider if a remote cache
-repository is provided.
-
-If you are building your own Devcontainer template, you can consult the
-[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
-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).
-
-## Devcontainer lifecycle scripts
-
-The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
-`postStartCommand` lifecycle scripts are run each time the container is started.
-This could be used, for example, to fetch or update project dependencies before
-a user begins using the workspace.
-
-Lifecycle scripts are managed by project developers.
-
-## Release channels
-
-Envbuilder provides two release channels:
-
-- **Stable**
- - Available at
- [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
- Tags `>=1.0.0` are considered stable.
-- **Preview**
- - Available at
- [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
- Built from the tip of `main`, and should be considered experimental and
- prone to breaking changes.
-
-Refer to the
-[Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more
-information and to submit feature requests or bug reports.
-
-## Known issues
-
-- Image caching: error pushing image
-
- - `BLOB_UNKNOWN: Manifest references unknown blob(s)`
- - [Issue 385](https://github.com/coder/envbuilder/issues/385)
-
-- Support for VS Code Extensions requires a workaround.
-
- - [Issue 68](https://github.com/coder/envbuilder/issues/68#issuecomment-1805974271)
-
-- Envbuilder does not support Volume Mounts
-
-- Support for lifecycle hooks is limited.
- ([Issue](https://github.com/coder/envbuilder/issues/395))
- - Supported:
- - `onCreateCommand`
- - `updateContentCommand`
- - `postCreateCommand`
- - `postStartCommand`
- - Not supported:
- - `initializeCommand`
- - `postAttachCommand`
- - `waitFor`
-
-Visit the
-[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
-for a full list of supported features and known issues.
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
new file mode 100644
index 0000000000000..b6db70a97ceb2
--- /dev/null
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -0,0 +1,79 @@
+# Add a devcontainer template to Coder
+
+A Coder administrator adds a devcontainer-compatible template to Coder
+(Envbuilder).
+
+When a developer creates their workspace, they enter their repository URL as a
+[parameter](../../extending-templates/parameters.md). Envbuilder clones the repo
+and builds a container from the `devcontainer.json` specified in the repo.
+
+Admin:
+
+1. Use a [devcontainer template](https://registry.coder.com/templates)
+1. Create a template with the template files from the registry (git clone,
+ upload files, or copy paste)
+1. In template settings > variables > set necessary variables such as the
+ namespace
+1. Create a workspace from the template
+1. Choose a **Repository** URL
+ - The repo must have a `.devcontainer` directory with `devcontainer.json`
+
+When using the
+[Envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder),
+a previously built and cached image can be reused directly, allowing dev
+containers to start instantaneously.
+
+Developers can edit the `devcontainer.json` in their workspace to customize
+their development environments:
+
+```json
+…
+"customizations": {
+ // Configure properties specific to VS Code.
+ "vscode": {
+ "settings": {
+ "editor.tabSize": 4,
+ "editor.detectIndentation": false
+ "editor.insertSpaces": true
+ "files.trimTrailingWhitespace": true
+ },
+ "extensions": [
+ "github.vscode-pull-request-github",
+ ]
+ }
+},
+…
+```
+
+## Example templates
+
+- [Docker devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
+ - Docker provisions a development container.
+- [Kubernetes devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
+ - Provisions a development container on the Kubernetes.
+- [Google Compute Engine devcontainer](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
+ - Runs a development container inside a single GCP instance. It also mounts
+ the Docker socket from the VM inside the container to enable Docker inside
+ the workspace.
+- [AWS EC2 devcontainer](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
+ - Runs a development container inside a single EC2 instance. It also mounts
+ the Docker socket from the VM inside the container to enable Docker inside
+ the workspace.
+
+Your template can prompt the user for a repo URL with
+[parameters](../../extending-templates/parameters.md):
+
+
+
+## Devcontainer lifecycle scripts
+
+The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
+`postStartCommand` lifecycle scripts are run each time the container is started.
+This could be used, for example, to fetch or update project dependencies before
+a user begins using the workspace.
+
+Lifecycle scripts are managed by project developers.
+
+## Next steps
+
+- [Devcontainer security and caching](./devcontainer-security-caching.md)
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
new file mode 100644
index 0000000000000..5be28ef53b50e
--- /dev/null
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
@@ -0,0 +1,48 @@
+# Devcontainer releases and known issues
+
+## Release channels
+
+Envbuilder provides two release channels:
+
+- **Stable**
+ - Available at
+ [`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
+ Tags `>=1.0.0` are considered stable.
+- **Preview**
+ - Available at
+ [`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
+ Built from the tip of `main`, and should be considered experimental and
+ prone to breaking changes.
+
+Refer to the
+[Envbuilder GitHub repository](https://github.com/coder/envbuilder/) for more
+information and to submit feature requests or bug reports.
+
+## Known issues
+
+- Image caching: error pushing image
+
+ - `BLOB_UNKNOWN: Manifest references unknown blob(s)`
+ - [Issue 385](https://github.com/coder/envbuilder/issues/385)
+
+- Support for VS Code Extensions requires a workaround.
+
+ - [Issue 68](https://github.com/coder/envbuilder/issues/68#issuecomment-1805974271)
+
+- Envbuilder does not support Volume Mounts
+
+- Support for lifecycle hooks is limited.
+ ([Issue](https://github.com/coder/envbuilder/issues/395))
+ - Supported:
+ - `onCreateCommand`
+ - `updateContentCommand`
+ - `postCreateCommand`
+ - `postStartCommand`
+ - Not supported:
+ - `initializeCommand`
+ - `postAttachCommand`
+ - `waitFor`
+
+Visit the
+[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
+for a full list of supported features and known issues.
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
new file mode 100644
index 0000000000000..3edff704668de
--- /dev/null
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -0,0 +1,67 @@
+# Devcontainer security and caching
+
+Ensure Envbuilder can only pull images and artifacts by configuring it with your
+existing HTTP proxies, firewalls, and artifact managers.
+
+### 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.
+
+## 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
+
+To improve build times, dev containers can be cached. There are two main forms
+of caching:
+
+- **Layer caching**
+
+ - Caches individual layers and pushes them to a remote registry. When building
+ the image, Envbuilder will check the remote registry for pre-existing layers
+ These will be fetched and extracted to disk instead of building the layers
+ from scratch.
+
+- **Image caching**
+ - Caches the entire image, skipping the build process completely (except for
+ post-build
+ [lifecycle scripts](./add-devcontainer.md#devcontainer-lifecycle-scripts)).
+
+Refer to the
+[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
+for more information.
+
+Note that caching requires push access to a registry, and may require approval.
+
+### Image caching
+
+To support resuming from a cached image, use the
+[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
+in your template. The provider will:
+
+1. Clone the remote Git repository,
+1. Perform a 'dry-run' build of the dev container in the same manner as
+ Envbuilder would,
+1. Check for the presence of a previously built image in the provided cache
+ repository,
+1. Output the image remote reference in SHA256 form, if it finds one.
+
+The example templates listed above will use the provider if a remote cache
+repository is provided.
+
+If you are building your own Devcontainer template, you can consult the
+[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
+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
+
+- [Devcontainer 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
new file mode 100644
index 0000000000000..232be225a7641
--- /dev/null
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -0,0 +1,82 @@
+# Development containers on Coder
+
+A development container (dev container or devcontainer) is an
+[open source specification](https://containers.dev/implementors/spec/) for
+defining containerized development environments.
+
+Leverage Coder with dev containers and apply cloud-native security practices to
+traditional ticket-ops and approval-ops workflows to help enable developers to
+self-service.
+
+## Benefits of devcontainers
+
+There are several benefits to adding a devcontainer-compatible template to
+Coder:
+
+- Reliability and scalability
+- Improved security
+- Performance efficiency
+- Cost Optimization
+
+### Reliability and scalability
+
+Envbuilder is an open source project independently packaged and versioned from
+the centralized Coder open source project. This means that it can be used with
+Coder, but it is not required. It also means that Dev Container builds can scale
+independently of the Coder control plane and even run in CI/CD.
+
+### 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 still require hardened base images and
+packages, while still allowing developer self service.
+
+### 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
+
+A development container
+
+## Coder Envbuilder
+
+Envbuilder is an open source project by Coder that runs dev containers via Coder
+templates and your underlying infrastructure. It can run on Docker or
+Kubernetes.
+
+Envbuilder uses the Dev Container standard used in VS Code Local, Daytona,
+DevPod, and Codespaces. This format is already familiar to developers and can
+simplify migration. This allows developers to take control of their own
+environments, while still following cloud-native security best practices. See
+the
+[Security section](./devcontainer-security-caching.md#devcontainer-security-and-caching)
+for more information.
+
+## Devcontainer Features
+
+[Devcontainer Features](https://containers.dev/implementors/features/) allow
+owners of a project to specify self-contained units of code and runtime
+configuration that can be composed together on top of an existing base image.
+This is a good place to install project-specific tools, such as
+language-specific runtimes and compilers.
+
+## Next steps
+
+- [Add a devcontainer template](./add-devcontainer.md)
diff --git a/docs/admin/templates/managing-templates/image-management.md b/docs/admin/templates/managing-templates/image-management.md
index cfb9880f0f53a..2f4cf2e43e4cb 100644
--- a/docs/admin/templates/managing-templates/image-management.md
+++ b/docs/admin/templates/managing-templates/image-management.md
@@ -70,4 +70,4 @@ specific tooling for their projects. The [Dev Container](https://containers.dev)
specification allows developers to define their projects dependencies within a
`devcontainer.json` in their Git repository.
-- [Learn how to integrate Dev Containers with Coder](./devcontainers.md)
+- [Learn how to integrate Dev Containers with Coder](./devcontainers/index.md)
diff --git a/docs/admin/templates/managing-templates/index.md b/docs/admin/templates/managing-templates/index.md
index 0abbac60487a6..a9e215bb71105 100644
--- a/docs/admin/templates/managing-templates/index.md
+++ b/docs/admin/templates/managing-templates/index.md
@@ -91,5 +91,5 @@ coder templates delete <template-name>
## Next steps
- [Image management](./image-management.md)
-- [Devcontainer templates](./devcontainers.md)
+- [Devcontainer templates](./devcontainers/index.md)
- [Change management](./change-management.md)
diff --git a/docs/manifest.json b/docs/manifest.json
index 9e13d24cc58e8..e8c3456bea043 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -323,7 +323,24 @@
{
"title": "Development containers on Coder",
"description": "Learn about using devcontainers in templates",
- "path": "./admin/templates/managing-templates/devcontainers.md"
+ "path": "./admin/templates/managing-templates/devcontainers/index.md",
+ "children": [
+ {
+ "title": "Add a devcontainer template",
+ "description": "How to add a devcontainer template to Coder",
+ "path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md"
+ },
+ {
+ "title": "Devcontainer security and caching",
+ "description": "Configure devcontainer authentication and caching",
+ "path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md"
+ },
+ {
+ "title": "Devcontainer releases and known issues",
+ "description": "Devcontainer releases and known issues",
+ "path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md"
+ }
+ ]
},
{
"title": "Template Dependencies",
From b24f615a20c0edced527769c69741844741575eb Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 20:16:05 +0000
Subject: [PATCH 09/36] fix typo
---
docs/admin/templates/index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md
index de8ab2cddaecc..af9ceace15ae3 100644
--- a/docs/admin/templates/index.md
+++ b/docs/admin/templates/index.md
@@ -48,7 +48,7 @@ needs of different teams.
- [Image management](./managing-templates/image-management.md): Learn how to
create and publish images for use within Coder workspaces & templates.
-- [Dev Container support](./managing-templates/devcontainers/index.md.md):
+- [Dev Container support](./managing-templates/devcontainers/index.md):
Enable dev containers to allow teams to bring their own tools into Coder
workspaces.
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
From 4c2841189b97228740a023811889161705411e79 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 13 Nov 2024 20:20:40 +0000
Subject: [PATCH 10/36] make fmt
---
docs/admin/templates/index.md | 5 ++---
1 file changed, 2 insertions(+), 3 deletions(-)
diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md
index af9ceace15ae3..85f2769e880bd 100644
--- a/docs/admin/templates/index.md
+++ b/docs/admin/templates/index.md
@@ -48,9 +48,8 @@ needs of different teams.
- [Image management](./managing-templates/image-management.md): Learn how to
create and publish images for use within Coder workspaces & templates.
-- [Dev Container support](./managing-templates/devcontainers/index.md):
- Enable dev containers to allow teams to bring their own tools into Coder
- workspaces.
+- [Dev Container support](./managing-templates/devcontainers/index.md): Enable
+ dev containers to allow teams to bring their own tools into Coder workspaces.
- [Template hardening](./extending-templates/resource-persistence.md#-bulletproofing):
Configure your template to prevent certain resources from being destroyed
(e.g. user disks).
From fc20dc3e981ff18ff45651b4c51a4355e92e5087 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 20 Nov 2024 17:46:13 +0000
Subject: [PATCH 11/36] suggestions from review
---
.../managing-templates/devcontainers/index.md | 89 +++++++++++++------
1 file changed, 61 insertions(+), 28 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index 232be225a7641..01a2430497407 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -1,29 +1,53 @@
# Development containers on Coder
-A development container (dev container or devcontainer) is an
+A Development Container is an
[open source specification](https://containers.dev/implementors/spec/) for
-defining containerized development environments.
+defining containerized development environments which are also called
+development containers (dev containers).
-Leverage Coder with dev containers and apply cloud-native security practices to
-traditional ticket-ops and approval-ops workflows to help enable developers to
-self-service.
+Use dev containers with Coder to give developers more autonomy and control over
+their environments while adding cloud-native security to standard ticket and
+approval workflows for increased self-service.
+
+## Prerequisites
+
+A developer team should configure dev containers after an administrator
+constructs or chooses a base image and creates a template that includes a
+`devcontainer_builder` image.
## Benefits of devcontainers
-There are several benefits to adding a devcontainer-compatible template to
+There are several benefits to adding a dev container-compatible template to
Coder:
-- Reliability and scalability
+- Reliability through standardization
+- Scalability for growing teams
- Improved security
- Performance efficiency
- Cost Optimization
-### Reliability and scalability
+### 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
-Envbuilder is an open source project independently packaged and versioned from
-the centralized Coder open source project. This means that it can be used with
-Coder, but it is not required. It also means that Dev Container builds can scale
-independently of the Coder control plane and even run in CI/CD.
+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.
+
+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.
### Improved security
@@ -34,7 +58,12 @@ Additionally, Envbuilder can be configured to push the full image back to your
registry for additional security scanning.
This means that Coder admins can still require hardened base images and
-packages, while still allowing developer self service.
+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
@@ -53,30 +82,34 @@ image caching ensures optimal start and stop times.
## When to use a dev container
-A development container
+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.
-## Coder Envbuilder
-
-Envbuilder is an open source project by Coder that runs dev containers via Coder
-templates and your underlying infrastructure. It can run on Docker or
-Kubernetes.
-
-Envbuilder uses the Dev Container standard used in VS Code Local, Daytona,
-DevPod, and Codespaces. This format is already familiar to developers and can
-simplify migration. This allows developers to take control of their own
-environments, while still following cloud-native security best practices. See
-the
-[Security section](./devcontainer-security-caching.md#devcontainer-security-and-caching)
-for more information.
+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.
## Devcontainer Features
-[Devcontainer Features](https://containers.dev/implementors/features/) allow
+[Dev container Features](https://containers.dev/implementors/features/) allow
owners of a project to specify self-contained units of code and runtime
configuration that can be composed together on top of an existing base image.
This is a good place to install project-specific tools, such as
language-specific runtimes and compilers.
+## Coder Envbuilder
+
+Envbuilder is an open-source project maintained by Coder that runs dev
+containers via Coder templates and your underlying infrastructure. Envbuilder
+can run on Docker or Kubernetes.
+
+It is independently packaged and versioned from the centralized Coder
+open-source project. This means that Envbuilder can be used with Coder, but it
+is not required. It also means that dev container builds can scale independently
+of the Coder control plane and even run within a CI/CD pipeline.
+
## Next steps
- [Add a devcontainer template](./add-devcontainer.md)
From 197cfa748576876d5ebd4c07b5be3d5305a7341d Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 20 Nov 2024 22:07:57 +0000
Subject: [PATCH 12/36] add steps in tabs to add-devcontainer
---
.../devcontainers/add-devcontainer.md | 85 ++++++++++++++++---
.../devcontainer-releases-known-issues.md | 25 +-----
.../devcontainer-security-caching.md | 8 +-
.../managing-templates/devcontainers/index.md | 2 +-
docs/manifest.json | 16 ++--
5 files changed, 89 insertions(+), 47 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index b6db70a97ceb2..4667242bb3810 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -1,15 +1,80 @@
-# Add a devcontainer template to Coder
+# Add a dev container template to Coder
-A Coder administrator adds a devcontainer-compatible template to Coder
+A Coder administrator adds a dev container-compatible template to Coder
(Envbuilder).
When a developer creates their workspace, they enter their repository URL as a
[parameter](../../extending-templates/parameters.md). Envbuilder clones the repo
and builds a container from the `devcontainer.json` specified in the repo.
+//tabs UI | CLI | Registry (/starter-templates?tag=devcontainer)
+
+<div class="tabs">
+
+## Dashboard
+
+1. In the Coder dashboard, select **Templates** then **Create Template**.
+1. To use a [starter template](https://github.com/coder/coder/tree/main/examples/templates), select **Choose a starter template**.
+ - Select **From scratch** to create a new template and enter information and file contents manually.
+
+## CLI
+
+1. Use the `template init` command to initialize your choice of image:
+
+ ```shell
+ coder template init --id devcontainer-kubernetes
+ ```
+
+1. `cd` into the directory and push the template to your Coder deployment:
+
+ ```shell
+ cd $_ && coder templates push
+ ```
+
+ You can also edit the files or make changes to the files before you push them to Coder.
+
+## Registry
+
+1. Go to the [Coder Registry](https://registry.coder.com/templates?tag=devcontainer) and select a dev container-compatible template.
+
+1. Copy the files to your local device, then edit them to fit your needs.
+
+1. Upload them to Coder through the CLI or dashboard:
+
+ - CLI:
+
+ ```shell
+ coder template push
+ ```
+
+ - Dashboard:
+
+ 1. Create a `.zip` of the template files:
+
+ - On Mac or Windows, highlight the files and then right click. A "compress" option is available through the right-click context menu.
+
+ - To zip the files through the command line:
+
+ ```shell
+ zip templates.zip Dockerfile main.tf
+ ```
+
+ 1. Select **Templates**.
+ 1. Select **Create Template**, then **Upload template**:
+
+ 
+
+ 1. Drag the `.zip` file into the **Upload template** section and fill out the details, then select **Create template**.
+
+ 
+
+ 1. Once the upload completes, select **Templates** from the top to deploy it to a new workspace.
+
+</div>
+
Admin:
-1. Use a [devcontainer template](https://registry.coder.com/templates)
+1. Use a [dev container template](https://registry.coder.com/templates)
1. Create a template with the template files from the registry (git clone,
upload files, or copy paste)
1. In template settings > variables > set necessary variables such as the
@@ -47,15 +112,15 @@ their development environments:
## Example templates
-- [Docker devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
+- [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- Docker provisions a development container.
-- [Kubernetes devcontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
+- [Kubernetes dev ontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- Provisions a development container on the Kubernetes.
-- [Google Compute Engine devcontainer](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
+- [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
- Runs a development container inside a single GCP instance. It also mounts
the Docker socket from the VM inside the container to enable Docker inside
the workspace.
-- [AWS EC2 devcontainer](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
+- [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
- Runs a development container inside a single EC2 instance. It also mounts
the Docker socket from the VM inside the container to enable Docker inside
the workspace.
@@ -63,9 +128,9 @@ their development environments:
Your template can prompt the user for a repo URL with
[parameters](../../extending-templates/parameters.md):
-
+
-## Devcontainer lifecycle scripts
+## Dev container lifecycle scripts
The `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, and
`postStartCommand` lifecycle scripts are run each time the container is started.
@@ -76,4 +141,4 @@ Lifecycle scripts are managed by project developers.
## Next steps
-- [Devcontainer security and caching](./devcontainer-security-caching.md)
+- [Dev container security and caching](./devcontainer-security-caching.md)
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
index 5be28ef53b50e..b8ba3bfddd21e 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md
@@ -1,4 +1,4 @@
-# Devcontainer releases and known issues
+# Dev container releases and known issues
## Release channels
@@ -20,29 +20,6 @@ information and to submit feature requests or bug reports.
## Known issues
-- Image caching: error pushing image
-
- - `BLOB_UNKNOWN: Manifest references unknown blob(s)`
- - [Issue 385](https://github.com/coder/envbuilder/issues/385)
-
-- Support for VS Code Extensions requires a workaround.
-
- - [Issue 68](https://github.com/coder/envbuilder/issues/68#issuecomment-1805974271)
-
-- Envbuilder does not support Volume Mounts
-
-- Support for lifecycle hooks is limited.
- ([Issue](https://github.com/coder/envbuilder/issues/395))
- - Supported:
- - `onCreateCommand`
- - `updateContentCommand`
- - `postCreateCommand`
- - `postStartCommand`
- - Not supported:
- - `initializeCommand`
- - `postAttachCommand`
- - `waitFor`
-
Visit the
[Envbuilder repository](https://github.com/coder/envbuilder/blob/main/docs/devcontainer-spec-support.md)
for a full list of supported features and known issues.
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index 3edff704668de..90d90a7344cf0 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -1,4 +1,4 @@
-# Devcontainer security and caching
+# Dev container security and caching
Ensure Envbuilder can only pull images and artifacts by configuring it with your
existing HTTP proxies, firewalls, and artifact managers.
@@ -47,7 +47,7 @@ To support resuming from a cached image, use the
in your template. The provider will:
1. Clone the remote Git repository,
-1. Perform a 'dry-run' build of the dev container in the same manner as
+1. Perform a "dry-run" build of the dev container in the same manner as
Envbuilder would,
1. Check for the presence of a previously built image in the provided cache
repository,
@@ -56,12 +56,12 @@ in your template. The provider will:
The example templates listed above will use the provider if a remote cache
repository is provided.
-If you are building your own Devcontainer template, you can consult the
+If you are building your own Dev container template, you can consult the
[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
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
-- [Devcontainer releases and known issues](./devcontainer-releases-known-issues.md)
+- [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
index 01a2430497407..2d8093b6883a6 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -1,4 +1,4 @@
-# Development containers on Coder
+# Development containers
A Development Container is an
[open source specification](https://containers.dev/implementors/spec/) for
diff --git a/docs/manifest.json b/docs/manifest.json
index e8c3456bea043..59fdb6d8487bd 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -321,23 +321,23 @@
"path": "./admin/templates/managing-templates/change-management.md"
},
{
- "title": "Development containers on Coder",
- "description": "Learn about using devcontainers in templates",
+ "title": "Development containers",
+ "description": "Learn about using dev containers in templates",
"path": "./admin/templates/managing-templates/devcontainers/index.md",
"children": [
{
- "title": "Add a devcontainer template",
- "description": "How to add a devcontainer template to Coder",
+ "title": "Add a dev container template",
+ "description": "How to add a dev container template to Coder",
"path": "./admin/templates/managing-templates/devcontainers/add-devcontainer.md"
},
{
- "title": "Devcontainer security and caching",
- "description": "Configure devcontainer authentication and caching",
+ "title": "Dev container security and caching",
+ "description": "Configure dev container authentication and caching",
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md"
},
{
- "title": "Devcontainer releases and known issues",
- "description": "Devcontainer releases and known issues",
+ "title": "Dev container releases and known issues",
+ "description": "Dev container releases and known issues",
"path": "./admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md"
}
]
From 5a93ff2d340608e72d4948404aeba2c261c7f28a Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 20 Nov 2024 22:14:35 +0000
Subject: [PATCH 13/36] fix links; list templates
---
.../managing-templates/devcontainers/add-devcontainer.md | 6 ++++--
.../devcontainers/devcontainer-security-caching.md | 2 +-
2 files changed, 5 insertions(+), 3 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 4667242bb3810..4258e90c98a23 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -25,6 +25,8 @@ and builds a container from the `devcontainer.json` specified in the repo.
coder template init --id devcontainer-kubernetes
```
+ A list of available templates is shown in the [templates_init](../../../../reference/cli/templates_init#--id) reference.
+
1. `cd` into the directory and push the template to your Coder deployment:
```shell
@@ -62,11 +64,11 @@ and builds a container from the `devcontainer.json` specified in the repo.
1. Select **Templates**.
1. Select **Create Template**, then **Upload template**:
- 
+ 
1. Drag the `.zip` file into the **Upload template** section and fill out the details, then select **Create template**.
- 
+ 
1. Once the upload completes, select **Templates** from the top to deploy it to a new workspace.
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index 90d90a7344cf0..ec3ebb5797213 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -32,7 +32,7 @@ of caching:
- **Image caching**
- Caches the entire image, skipping the build process completely (except for
post-build
- [lifecycle scripts](./add-devcontainer.md#devcontainer-lifecycle-scripts)).
+ [lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
From 8e5373531a4703f057c9bed4ad3f8a63def118c3 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Wed, 20 Nov 2024 22:16:23 +0000
Subject: [PATCH 14/36] make fmt + copy review addition
---
.../devcontainers/add-devcontainer.md | 45 ++++++++++++-------
.../managing-templates/devcontainers/index.md | 10 +++--
2 files changed, 35 insertions(+), 20 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 4258e90c98a23..427ea2a0b57d3 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -14,8 +14,12 @@ and builds a container from the `devcontainer.json` specified in the repo.
## Dashboard
1. In the Coder dashboard, select **Templates** then **Create Template**.
-1. To use a [starter template](https://github.com/coder/coder/tree/main/examples/templates), select **Choose a starter template**.
- - Select **From scratch** to create a new template and enter information and file contents manually.
+1. To use a
+ [starter template](https://github.com/coder/coder/tree/main/examples/templates),
+ select **Choose a starter template**.
+
+- Select **From scratch** to create a new template and enter information and
+ file contents manually.
## CLI
@@ -25,7 +29,8 @@ and builds a container from the `devcontainer.json` specified in the repo.
coder template init --id devcontainer-kubernetes
```
- A list of available templates is shown in the [templates_init](../../../../reference/cli/templates_init#--id) reference.
+ A list of available templates is shown in the
+ [templates_init](../../../../reference/cli/templates_init#--id) reference.
1. `cd` into the directory and push the template to your Coder deployment:
@@ -33,18 +38,21 @@ and builds a container from the `devcontainer.json` specified in the repo.
cd $_ && coder templates push
```
- You can also edit the files or make changes to the files before you push them to Coder.
+ You can also edit the files or make changes to the files before you push them
+ to Coder.
## Registry
-1. Go to the [Coder Registry](https://registry.coder.com/templates?tag=devcontainer) and select a dev container-compatible template.
+1. Go to the
+ [Coder Registry](https://registry.coder.com/templates?tag=devcontainer) and
+ select a dev container-compatible template.
1. Copy the files to your local device, then edit them to fit your needs.
1. Upload them to Coder through the CLI or dashboard:
- CLI:
-
+
```shell
coder template push
```
@@ -53,24 +61,27 @@ and builds a container from the `devcontainer.json` specified in the repo.
1. Create a `.zip` of the template files:
- - On Mac or Windows, highlight the files and then right click. A "compress" option is available through the right-click context menu.
+ - On Mac or Windows, highlight the files and then right click. A
+ "compress" option is available through the right-click context menu.
- - To zip the files through the command line:
+ - To zip the files through the command line:
- ```shell
- zip templates.zip Dockerfile main.tf
- ```
+ ```shell
+ zip templates.zip Dockerfile main.tf
+ ```
1. Select **Templates**.
1. Select **Create Template**, then **Upload template**:
- 
-
- 1. Drag the `.zip` file into the **Upload template** section and fill out the details, then select **Create template**.
+ 
+
+ 1. Drag the `.zip` file into the **Upload template** section and fill out
+ the details, then select **Create template**.
+
+ 
- 
-
- 1. Once the upload completes, select **Templates** from the top to deploy it to a new workspace.
+ 1. Once the upload completes, select **Templates** from the top to deploy
+ it to a new workspace.
</div>
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index 2d8093b6883a6..a47413638a1fa 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -5,9 +5,13 @@ A Development Container is an
defining containerized development environments which are also called
development containers (dev containers).
-Use dev containers with Coder to give developers more autonomy and control over
-their environments while adding cloud-native security to standard ticket and
-approval workflows for increased self-service.
+Dev containers provide developers with increased autonomy and control over their
+Coder cloud development environments.
+
+By using dev containers, developers can customize their workspaces with tools
+pre-approved by platform teams in registries like JFrog Artifactory. This
+simplifies workflows, reduces the need for tickets and approvals, and promotes
+greater independence for developers.
## Prerequisites
From 80bf5dab650af5bb71a102a69ac75ae3784a943c Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Thu, 21 Nov 2024 19:31:28 +0000
Subject: [PATCH 15/36] fix link
---
.../managing-templates/devcontainers/add-devcontainer.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 427ea2a0b57d3..21a5c49c33f48 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -30,7 +30,7 @@ and builds a container from the `devcontainer.json` specified in the repo.
```
A list of available templates is shown in the
- [templates_init](../../../../reference/cli/templates_init#--id) reference.
+ [templates_init](../../../../reference/cli/templates.md) reference.
1. `cd` into the directory and push the template to your Coder deployment:
From ca56186627576a6b7a38952696bd75881bcb86e7 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Thu, 21 Nov 2024 20:02:51 +0000
Subject: [PATCH 16/36] typo fix
---
.../managing-templates/devcontainers/add-devcontainer.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 21a5c49c33f48..d107746500daf 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -127,8 +127,8 @@ their development environments:
- [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- Docker provisions a development container.
-- [Kubernetes dev ontainers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- - Provisions a development container on the Kubernetes.
+- [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
+ - Provisions a development container on the Kubernetes cluster.
- [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
- Runs a development container inside a single GCP instance. It also mounts
the Docker socket from the VM inside the container to enable Docker inside
From 1491680049178d13a2d183c76fc3082126d3d2d2 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Thu, 21 Nov 2024 21:53:04 +0000
Subject: [PATCH 17/36] copy edit devcontainer/index
---
.../devcontainers/add-devcontainer.md | 4 ++--
.../devcontainer-security-caching.md | 1 +
.../managing-templates/devcontainers/index.md | 24 ++++++++++---------
3 files changed, 16 insertions(+), 13 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index d107746500daf..d9d1a27ed28eb 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -18,8 +18,8 @@ and builds a container from the `devcontainer.json` specified in the repo.
[starter template](https://github.com/coder/coder/tree/main/examples/templates),
select **Choose a starter template**.
-- Select **From scratch** to create a new template and enter information and
- file contents manually.
+ - Select **From scratch** to create a new template and enter information and
+ file contents manually.
## CLI
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index ec3ebb5797213..e9dec754af04d 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -30,6 +30,7 @@ of caching:
from scratch.
- **Image caching**
+
- Caches the entire image, skipping the build process completely (except for
post-build
[lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index a47413638a1fa..9eb953e67062b 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -1,7 +1,7 @@
# Development containers
A Development Container is an
-[open source specification](https://containers.dev/implementors/spec/) for
+[open-source specification](https://containers.dev/implementors/spec/) for
defining containerized development environments which are also called
development containers (dev containers).
@@ -15,9 +15,9 @@ greater independence for developers.
## Prerequisites
-A developer team should configure dev containers after an administrator
-constructs or chooses a base image and creates a template that includes a
-`devcontainer_builder` image.
+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
@@ -34,10 +34,12 @@ Coder:
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.
+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
@@ -61,8 +63,8 @@ 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 still require hardened base images and
-packages, while still allowing developer self-service.
+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
@@ -116,4 +118,4 @@ of the Coder control plane and even run within a CI/CD pipeline.
## Next steps
-- [Add a devcontainer template](./add-devcontainer.md)
+- [Add a dev container template](./add-devcontainer.md)
From 7f8b0793322c45749518de5563bb8aaaddbd4e16 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 19:02:00 +0000
Subject: [PATCH 18/36] edit add-devcontainer
---
.../devcontainers/add-devcontainer.md | 59 ++++++++-----------
1 file changed, 24 insertions(+), 35 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index d9d1a27ed28eb..a989cdaec8356 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -1,13 +1,10 @@
# Add a dev container template to Coder
A Coder administrator adds a dev container-compatible template to Coder
-(Envbuilder).
-
-When a developer creates their workspace, they enter their repository URL as a
-[parameter](../../extending-templates/parameters.md). Envbuilder clones the repo
+(Envbuilder). This allows the template to prompt for the developer for their dev container repository's URL as a [parameter](../../extending-templates/parameters.md) when they create their workspace. Envbuilder clones the repo
and builds a container from the `devcontainer.json` specified in the repo.
-//tabs UI | CLI | Registry (/starter-templates?tag=devcontainer)
+You can create template files through the Coder dashboard, CLI, or you can choose a template from the [Coder registry](https://registry.coder.com/templates?tag=devcontainer):
<div class="tabs">
@@ -19,7 +16,7 @@ and builds a container from the `devcontainer.json` specified in the repo.
select **Choose a starter template**.
- Select **From scratch** to create a new template and enter information and
- file contents manually.
+ file contents manually.
## CLI
@@ -44,7 +41,7 @@ and builds a container from the `devcontainer.json` specified in the repo.
## Registry
1. Go to the
- [Coder Registry](https://registry.coder.com/templates?tag=devcontainer) and
+ [Coder registry](https://registry.coder.com/templates?tag=devcontainer) and
select a dev container-compatible template.
1. Copy the files to your local device, then edit them to fit your needs.
@@ -53,48 +50,40 @@ and builds a container from the `devcontainer.json` specified in the repo.
- CLI:
- ```shell
- coder template push
- ```
+ ```shell
+ coder template push
+ ```
- Dashboard:
- 1. Create a `.zip` of the template files:
+ 1. Create a `.zip` of the template files:
- - On Mac or Windows, highlight the files and then right click. A
- "compress" option is available through the right-click context menu.
+ - On Mac or Windows, highlight the files and then right click. A
+ "compress" option is available through the right-click context menu.
- - To zip the files through the command line:
+ - To zip the files through the command line:
- ```shell
- zip templates.zip Dockerfile main.tf
- ```
+ ```shell
+ zip templates.zip Dockerfile main.tf
+ ```
- 1. Select **Templates**.
- 1. Select **Create Template**, then **Upload template**:
+ 1. Select **Templates**.
+ 1. Select **Create Template**, then **Upload template**:
- 
+ 
- 1. Drag the `.zip` file into the **Upload template** section and fill out
- the details, then select **Create template**.
+ 1. Drag the `.zip` file into the **Upload template** section and fill out
+ the details, then select **Create template**.
- 
-
- 1. Once the upload completes, select **Templates** from the top to deploy
- it to a new workspace.
+ 
</div>
-Admin:
+To set variables such as the namespace, go to the template in your Coder dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
+
+
-1. Use a [dev container template](https://registry.coder.com/templates)
-1. Create a template with the template files from the registry (git clone,
- upload files, or copy paste)
-1. In template settings > variables > set necessary variables such as the
- namespace
-1. Create a workspace from the template
-1. Choose a **Repository** URL
- - The repo must have a `.devcontainer` directory with `devcontainer.json`
+## Envbuilder Terraform provider
When using the
[Envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder),
From 547cfe0453420ced083f498e6d56de8b1dbef7ac Mon Sep 17 00:00:00 2001
From: Edward Angert <EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 15:05:24 -0500
Subject: [PATCH 19/36] Apply suggestions from code review
Co-authored-by: Cian Johnston <cian@coder.com>
---
docs/admin/index.md | 9 +++++++--
.../devcontainers/devcontainer-security-caching.md | 11 ++---------
2 files changed, 9 insertions(+), 11 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 26e429de83ae9..d7b3155490267 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -50,8 +50,13 @@ For any information not strictly contained in these sections, check out our
- **Development containers**
- - more about devcontainers...
- - Managed by:
+```suggestion
+ - A [development container](../managing-templates/devcontainers.md) is an
+ open-source specification for defining development environments. It is
+ generally stored in VCS alongside associated source code. It can
+ reference an existing base image, or a custom Dockerfile that will be built
+ on-demand.
+ - Managed by: developers
- **Dotfiles / personalization**
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index e9dec754af04d..8a6fd4c20172a 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -1,6 +1,6 @@
# Dev container security and caching
-Ensure Envbuilder can only pull images and artifacts by configuring it with your
+Ensure Envbuilder can only pull pre-approved images and artifacts by configuring it with your
existing HTTP proxies, firewalls, and artifact managers.
### Configure registry authentication
@@ -10,13 +10,6 @@ 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.
-## 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
To improve build times, dev containers can be cached. There are two main forms
@@ -39,7 +32,7 @@ Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
for more information.
-Note that caching requires push access to a registry, and may require approval.
+Note that caching requires push access to a registry, and may require approval from relevant infrastructure team(s).
### Image caching
From d22f76f59ca8fbe0e9dc865c38d74797054b6bdf Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 19:58:24 +0000
Subject: [PATCH 20/36] add screenshot
---
.../devcontainers/add-devcontainer.md | 28 +++++++++++-------
.../templates/template-menu-settings.png | Bin 0 -> 14884 bytes
2 files changed, 17 insertions(+), 11 deletions(-)
create mode 100644 docs/images/templates/template-menu-settings.png
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index a989cdaec8356..74aafdca480d8 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -1,10 +1,15 @@
# Add a dev container template to Coder
A Coder administrator adds a dev container-compatible template to Coder
-(Envbuilder). This allows the template to prompt for the developer for their dev container repository's URL as a [parameter](../../extending-templates/parameters.md) when they create their workspace. Envbuilder clones the repo
-and builds a container from the `devcontainer.json` specified in the repo.
+(Envbuilder). This allows the template to prompt for the developer for their dev
+container repository's URL as a
+[parameter](../../extending-templates/parameters.md) when they create their
+workspace. Envbuilder clones the repo and builds a container from the
+`devcontainer.json` specified in the repo.
-You can create template files through the Coder dashboard, CLI, or you can choose a template from the [Coder registry](https://registry.coder.com/templates?tag=devcontainer):
+You can create template files through the Coder dashboard, CLI, or you can
+choose a template from the
+[Coder registry](https://registry.coder.com/templates?tag=devcontainer):
<div class="tabs">
@@ -16,7 +21,7 @@ You can create template files through the Coder dashboard, CLI, or you can choos
select **Choose a starter template**.
- Select **From scratch** to create a new template and enter information and
- file contents manually.
+ file contents manually.
## CLI
@@ -59,27 +64,28 @@ You can create template files through the Coder dashboard, CLI, or you can choos
1. Create a `.zip` of the template files:
- On Mac or Windows, highlight the files and then right click. A
- "compress" option is available through the right-click context menu.
+ "compress" option is available through the right-click context menu.
- To zip the files through the command line:
- ```shell
- zip templates.zip Dockerfile main.tf
- ```
+ ```shell
+ zip templates.zip Dockerfile main.tf
+ ```
1. Select **Templates**.
1. Select **Create Template**, then **Upload template**:
- 1. Drag the `.zip` file into the **Upload template** section and fill out
- the details, then select **Create template**.
+ 1. Drag the `.zip` file into the **Upload template** section and fill out the
+ details, then select **Create template**.
</div>
-To set variables such as the namespace, go to the template in your Coder dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
+To set variables such as the namespace, go to the template in your Coder
+dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
diff --git a/docs/images/templates/template-menu-settings.png b/docs/images/templates/template-menu-settings.png
new file mode 100644
index 0000000000000000000000000000000000000000..cac2aca1462c07a6c569e791b59030fea9061ca5
GIT binary patch
literal 14884
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
AHvj+t
literal 0
HcmV?d00001
From ce0d2be5a3f56109f450651ca287525a922fe02d Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 20:10:28 +0000
Subject: [PATCH 21/36] make fmt; copy tweaks
---
docs/admin/index.md | 18 ++++++++----------
.../devcontainers/add-devcontainer.md | 19 +++++--------------
.../devcontainer-security-caching.md | 7 ++++---
3 files changed, 17 insertions(+), 27 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index d7b3155490267..9932bb4b0f35c 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -20,10 +20,10 @@ For any information not strictly contained in these sections, check out our
- **Image**
- A [base image](./templates/managing-templates/image-management.md) contains
- the operating system (OS), OS-level packages, and utilities that the Coder
- workspace is built on. It can be an
- [example image](https://github.com/coder/images), custom image, or one from
- [Docker Hub](https://hub.docker.com/search). It is defined in each template.
+ OS-level packages, and utilities that the Coder workspace is built on. It
+ can be an [example image](https://github.com/coder/images), custom image, or
+ one from [Docker Hub](https://hub.docker.com/search). It is defined in each
+ template.
- Managed by: Externally to Coder.
- **Template**
@@ -46,17 +46,15 @@ For any information not strictly contained in these sections, check out our
that a developer works in. Developers on a team each work from their own
workspace and can use
[multiple IDEs](../user-guides/workspace-access/index.md).
- - Managed by:
+ - Managed by: Developers
- **Development containers**
-```suggestion
- A [development container](../managing-templates/devcontainers.md) is an
open-source specification for defining development environments. It is
- generally stored in VCS alongside associated source code. It can
- reference an existing base image, or a custom Dockerfile that will be built
- on-demand.
- - Managed by: developers
+ generally stored in VCS alongside associated source code. It can reference
+ an existing base image, or a custom Dockerfile that will be built on-demand.
+ - Managed by: Developers
- **Dotfiles / personalization**
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 74aafdca480d8..0086a976be181 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -101,20 +101,11 @@ their development environments:
```json
…
-"customizations": {
- // Configure properties specific to VS Code.
- "vscode": {
- "settings": {
- "editor.tabSize": 4,
- "editor.detectIndentation": false
- "editor.insertSpaces": true
- "files.trimTrailingWhitespace": true
- },
- "extensions": [
- "github.vscode-pull-request-github",
- ]
- }
-},
+{
+ "features": {
+ "ghcr.io/devcontainers/features/common-utils:2": {}
+ }
+}
…
```
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index 8a6fd4c20172a..d36d75ef45cf3 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -1,7 +1,7 @@
# 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.
+Ensure Envbuilder can only pull pre-approved images and artifacts by configuring
+it with your existing HTTP proxies, firewalls, and artifact managers.
### Configure registry authentication
@@ -32,7 +32,8 @@ Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
for more information.
-Note that caching requires push access to a registry, and may require approval from relevant infrastructure team(s).
+Note that caching requires push access to a registry, and may require approval
+from relevant infrastructure team(s).
### Image caching
From 66fcca033ad774ff37aecba7e673f5477ea5cb63 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 20:15:15 +0000
Subject: [PATCH 22/36] edit example
---
.../managing-templates/devcontainers/add-devcontainer.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 0086a976be181..68e93b074f9a5 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -56,7 +56,7 @@ choose a template from the
- CLI:
```shell
- coder template push
+ coder templates push <template-name> -d <path to folder containing main.tf>
```
- Dashboard:
From de581599d992e1f897b504ca3b0303f20d6a16f7 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 20:16:52 +0000
Subject: [PATCH 23/36] link typo
---
docs/admin/index.md | 5 +++--
1 file changed, 3 insertions(+), 2 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 9932bb4b0f35c..7d371f68172b9 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -50,8 +50,9 @@ For any information not strictly contained in these sections, check out our
- **Development containers**
- - A [development container](../managing-templates/devcontainers.md) is an
- open-source specification for defining development environments. It is
+ - A
+ [development container](./templates/managing-templates/devcontainers/index.md)
+ is an open-source specification for defining development environments. It is
generally stored in VCS alongside associated source code. It can reference
an existing base image, or a custom Dockerfile that will be built on-demand.
- Managed by: Developers
From 69415d4ba55c43c9dbe476d58d911a6681ce310b Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Fri, 22 Nov 2024 20:20:57 +0000
Subject: [PATCH 24/36] adjust image size
---
.../managing-templates/devcontainers/add-devcontainer.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 68e93b074f9a5..4374704fa8103 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -87,7 +87,7 @@ choose a template from the
To set variables such as the namespace, go to the template in your Coder
dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
-
+<Image height="255px" src="../../../../images/templates/template-menu-settings.png" alt="Choose Settings from the template's menu" align="center" />
## Envbuilder Terraform provider
From ae543de6d4f5b00c556e9c37e477c23a6df3c3f9 Mon Sep 17 00:00:00 2001
From: Edward Angert <EdwardAngert@users.noreply.github.com>
Date: Mon, 25 Nov 2024 10:53:39 -0500
Subject: [PATCH 25/36] Apply suggestions from code review
Co-authored-by: Ben Potter <ben@coder.com>
---
docs/admin/index.md | 12 ++++++------
.../devcontainers/add-devcontainer.md | 5 ++---
2 files changed, 8 insertions(+), 9 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 7d371f68172b9..fd7475155038e 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -21,7 +21,7 @@ For any information not strictly contained in these sections, check out our
- A [base image](./templates/managing-templates/image-management.md) contains
OS-level packages, and utilities that the Coder workspace is built on. It
- can be an [example image](https://github.com/coder/images), custom image, or
+ can be an [example image](https://github.com/coder/images), custom image in your registry, or
one from [Docker Hub](https://hub.docker.com/search). It is defined in each
template.
- Managed by: Externally to Coder.
@@ -48,14 +48,14 @@ For any information not strictly contained in these sections, check out our
[multiple IDEs](../user-guides/workspace-access/index.md).
- Managed by: Developers
-- **Development containers**
+- **Development containers (dev containers)**
- A
- [development container](./templates/managing-templates/devcontainers/index.md)
- is an open-source specification for defining development environments. It is
+ [Development Container](./templates/managing-templates/devcontainers/index.md)
+ is an open-source specification for defining development environments (called dev containers). It is
generally stored in VCS alongside associated source code. It can reference
an existing base image, or a custom Dockerfile that will be built on-demand.
- - Managed by: Developers
+ - Managed by: Dev Teams
- **Dotfiles / personalization**
@@ -65,6 +65,6 @@ For any information not strictly contained in these sections, check out our
script to personalize their workspace. Be aware that users with root
permissions in their workspace can override almost all of the previous
configuration.
- - Managed by: User
+ - Managed by: Individual Users
<children></children>
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 4374704fa8103..443f45412971e 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -100,14 +100,13 @@ Developers can edit the `devcontainer.json` in their workspace to customize
their development environments:
```json
-…
+# …
{
"features": {
"ghcr.io/devcontainers/features/common-utils:2": {}
}
}
-…
-```
+# …
## Example templates
From ca0da6dd6f02e0a084bd1ab434963b716cd88c9a Mon Sep 17 00:00:00 2001
From: Edward Angert <EdwardAngert@users.noreply.github.com>
Date: Mon, 25 Nov 2024 10:55:24 -0500
Subject: [PATCH 26/36] Apply suggestions from code review
---
.../managing-templates/devcontainers/add-devcontainer.md | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 443f45412971e..917c7e341d694 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -9,7 +9,7 @@ workspace. Envbuilder clones the repo and builds a container from the
You can create template files through the Coder dashboard, CLI, or you can
choose a template from the
-[Coder registry](https://registry.coder.com/templates?tag=devcontainer):
+[Coder registry](https://registry.coder.com/templates):
<div class="tabs">
@@ -92,7 +92,7 @@ dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu:
## Envbuilder Terraform provider
When using the
-[Envbuilder Terraform provider](https://github.com/coder/terraform-provider-envbuilder),
+[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs),
a previously built and cached image can be reused directly, allowing dev
containers to start instantaneously.
From 381bb7368c6fae999c3b1bd797a11a51a06e15ea Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Mon, 25 Nov 2024 15:56:14 +0000
Subject: [PATCH 27/36] make fmt
---
docs/admin/index.md | 13 +++++++------
.../devcontainers/add-devcontainer.md | 1 +
2 files changed, 8 insertions(+), 6 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index fd7475155038e..d4516ba520311 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -21,9 +21,9 @@ For any information not strictly contained in these sections, check out our
- A [base image](./templates/managing-templates/image-management.md) contains
OS-level packages, and utilities that the Coder workspace is built on. It
- can be an [example image](https://github.com/coder/images), custom image in your registry, or
- one from [Docker Hub](https://hub.docker.com/search). It is defined in each
- template.
+ can be an [example image](https://github.com/coder/images), custom image in
+ your registry, or one from [Docker Hub](https://hub.docker.com/search). It
+ is defined in each template.
- Managed by: Externally to Coder.
- **Template**
@@ -52,9 +52,10 @@ For any information not strictly contained in these sections, check out our
- A
[Development Container](./templates/managing-templates/devcontainers/index.md)
- is an open-source specification for defining development environments (called dev containers). It is
- generally stored in VCS alongside associated source code. It can reference
- an existing base image, or a custom Dockerfile that will be built on-demand.
+ is an open-source specification for defining development environments
+ (called dev containers). It is generally stored in VCS alongside associated
+ source code. It can reference an existing base image, or a custom Dockerfile
+ that will be built on-demand.
- Managed by: Dev Teams
- **Dotfiles / personalization**
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 917c7e341d694..e88f453505b01 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -140,3 +140,4 @@ Lifecycle scripts are managed by project developers.
## Next steps
- [Dev container security and caching](./devcontainer-security-caching.md)
+```
From ade54e9e648388207dc87004eddc34afee1b3346 Mon Sep 17 00:00:00 2001
From: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>
Date: Mon, 25 Nov 2024 19:51:34 +0000
Subject: [PATCH 28/36] close codeblock; edit starter template steps
---
.../devcontainers/add-devcontainer.md | 31 +++++++++++++------
1 file changed, 22 insertions(+), 9 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index e88f453505b01..7f79d2c8ca1eb 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -16,12 +16,22 @@ choose a template from the
## Dashboard
1. In the Coder dashboard, select **Templates** then **Create Template**.
-1. To use a
- [starter template](https://github.com/coder/coder/tree/main/examples/templates),
- select **Choose a starter template**.
+1. Use a
+ [starter template](https://github.com/coder/coder/tree/main/examples/templates)
+ or create a new template:
- - Select **From scratch** to create a new template and enter information and
- file contents manually.
+ - Starter template:
+
+ 1. Select **Choose a starter template**.
+ 1. Choose a template from the list or select **Devcontainer** from the
+ sidebar to display only dev container-compatible templates.
+ 1. Select **Use template**, enter the details, then select **Create
+ template**.
+
+ - To create a new template, select **From scratch** and enter the templates
+ details, then select **Create template**.
+
+1. Edit the template files to fit your deployment.
## CLI
@@ -37,7 +47,7 @@ choose a template from the
1. `cd` into the directory and push the template to your Coder deployment:
```shell
- cd $_ && coder templates push
+ cd devcontainer-kubernetes && coder templates push
```
You can also edit the files or make changes to the files before you push them
@@ -45,9 +55,8 @@ choose a template from the
## Registry
-1. Go to the
- [Coder registry](https://registry.coder.com/templates?tag=devcontainer) and
- select a dev container-compatible template.
+1. Go to the [Coder registry](https://registry.coder.com/templates) and select a
+ dev container-compatible template.
1. Copy the files to your local device, then edit them to fit your needs.
@@ -107,6 +116,7 @@ their development environments:
}
}
# …
+```
## Example templates
@@ -140,4 +150,7 @@ Lifecycle scripts are managed by project developers.
## Next steps
- [Dev container security and caching](./devcontainer-security-caching.md)
+
+```
+
```
From e46fc1359737ab5ddf585ce5c4297036815000ae Mon Sep 17 00:00:00 2001
From: Edward Angert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:18:09 +0000
Subject: [PATCH 29/36] code review
---
.../devcontainers/devcontainer-security-caching.md | 8 +++++---
.../templates/managing-templates/devcontainers/index.md | 4 ++--
2 files changed, 7 insertions(+), 5 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index d36d75ef45cf3..bebb593ebb192 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -28,12 +28,14 @@ of caching:
post-build
[lifecycle scripts](./add-devcontainer.md#dev-container-lifecycle-scripts)).
+Note that caching requires push access to a registry, and may require approval
+from relevant infrastructure team(s).
+
Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
-for more information.
+for more information about Envbuilder and caching.
-Note that caching requires push access to a registry, and may require approval
-from relevant infrastructure team(s).
+Visit the [speed up templates](../../../../tutorials/best-practices/speed-up-templates.md) best practice documentation for more ways that you can speed up build times.
### Image caching
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index 9eb953e67062b..fa194262ec1c6 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -9,7 +9,7 @@ Dev containers provide developers with increased autonomy and control over their
Coder cloud development environments.
By using dev containers, developers can customize their workspaces with tools
-pre-approved by platform teams in registries like JFrog Artifactory. This
+pre-approved by platform teams in registries like [JFrog Artifactory](../../../integrations/jfrog-artifactory.md). This
simplifies workflows, reduces the need for tickets and approvals, and promotes
greater independence for developers.
@@ -107,7 +107,7 @@ language-specific runtimes and compilers.
## Coder Envbuilder
-Envbuilder is an open-source project maintained by Coder that runs dev
+[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project maintained by Coder that runs dev
containers via Coder templates and your underlying infrastructure. Envbuilder
can run on Docker or Kubernetes.
From 9982af4612867211e9d50a16d6b30fb0406f3471 Mon Sep 17 00:00:00 2001
From: Edward Angert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:24:21 +0000
Subject: [PATCH 30/36] make fmt
---
.../devcontainers/devcontainer-security-caching.md | 4 +++-
.../managing-templates/devcontainers/index.md | 13 +++++++------
2 files changed, 10 insertions(+), 7 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
index bebb593ebb192..bb56ff6a31e32 100644
--- a/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
+++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md
@@ -35,7 +35,9 @@ Refer to the
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
for more information about Envbuilder and caching.
-Visit the [speed up templates](../../../../tutorials/best-practices/speed-up-templates.md) best practice documentation for more ways that you can speed up build times.
+Visit the
+[speed up templates](../../../../tutorials/best-practices/speed-up-templates.md)
+best practice documentation for more ways that you can speed up build times.
### Image caching
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index fa194262ec1c6..6ecdff9ccb2b1 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -9,9 +9,10 @@ Dev containers provide developers with increased autonomy and control over their
Coder cloud development environments.
By using dev containers, developers can customize their workspaces with tools
-pre-approved by platform teams in registries like [JFrog Artifactory](../../../integrations/jfrog-artifactory.md). This
-simplifies workflows, reduces the need for tickets and approvals, and promotes
-greater independence for developers.
+pre-approved by platform teams in registries like
+[JFrog Artifactory](../../../integrations/jfrog-artifactory.md). This simplifies
+workflows, reduces the need for tickets and approvals, and promotes greater
+independence for developers.
## Prerequisites
@@ -107,9 +108,9 @@ language-specific runtimes and compilers.
## Coder Envbuilder
-[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project maintained by Coder that runs dev
-containers via Coder templates and your underlying infrastructure. Envbuilder
-can run on Docker or Kubernetes.
+[Envbuilder](https://github.com/coder/envbuilder/) is an open-source project
+maintained by Coder that runs dev containers via Coder templates and your
+underlying infrastructure. Envbuilder can run on Docker or Kubernetes.
It is independently packaged and versioned from the centralized Coder
open-source project. This means that Envbuilder can be used with Coder, but it
From 182d69a44919664eb182afa496e7c7b9ca861864 Mon Sep 17 00:00:00 2001
From: Edward Angert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:34:40 +0000
Subject: [PATCH 31/36] rename to dev containers
---
.../admin/templates/managing-templates/devcontainers/index.md | 2 +-
docs/manifest.json | 4 ++--
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/index.md b/docs/admin/templates/managing-templates/devcontainers/index.md
index 6ecdff9ccb2b1..a4ec140765a4c 100644
--- a/docs/admin/templates/managing-templates/devcontainers/index.md
+++ b/docs/admin/templates/managing-templates/devcontainers/index.md
@@ -1,4 +1,4 @@
-# Development containers
+# Dev containers
A Development Container is an
[open-source specification](https://containers.dev/implementors/spec/) for
diff --git a/docs/manifest.json b/docs/manifest.json
index 59fdb6d8487bd..e60d4752d8c12 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -321,8 +321,8 @@
"path": "./admin/templates/managing-templates/change-management.md"
},
{
- "title": "Development containers",
- "description": "Learn about using dev containers in templates",
+ "title": "Dev containers",
+ "description": "Learn about using development containers in templates",
"path": "./admin/templates/managing-templates/devcontainers/index.md",
"children": [
{
From bf2e0fa2a0c11c52cbc7c26e843788d0979b808f Mon Sep 17 00:00:00 2001
From: Edward Angert <EdwardAngert@users.noreply.github.com>
Date: Tue, 26 Nov 2024 14:35:45 -0500
Subject: [PATCH 32/36] 2-col table
Co-authored-by: Muhammad Atif Ali <atif@coder.com>
---
.../devcontainers/add-devcontainer.md | 18 ++++++------------
1 file changed, 6 insertions(+), 12 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index 7f79d2c8ca1eb..cb646c9a5d03a 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -120,18 +120,12 @@ their development environments:
## Example templates
-- [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- - Docker provisions a development container.
-- [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- - Provisions a development container on the Kubernetes cluster.
-- [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
- - Runs a development container inside a single GCP instance. It also mounts
- the Docker socket from the VM inside the container to enable Docker inside
- the workspace.
-- [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
- - Runs a development container inside a single EC2 instance. It also mounts
- the Docker socket from the VM inside the container to enable Docker inside
- the workspace.
+| Template | Description |
+| -------- | ----------- |
+| [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker) | Docker provisions a development container. |
+| [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes) | Provisions a development container on the Kubernetes cluster. |
+| [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
+| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
Your template can prompt the user for a repo URL with
[parameters](../../extending-templates/parameters.md):
From cd99937b5e1f1f78d01cacac9bdb7f7a5279c684 Mon Sep 17 00:00:00 2001
From: Edward Angert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:36:46 +0000
Subject: [PATCH 33/36] make fmt
---
.../devcontainers/add-devcontainer.md | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
index cb646c9a5d03a..18dabcf2b23b3 100644
--- a/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
+++ b/docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md
@@ -120,12 +120,12 @@ their development environments:
## Example templates
-| Template | Description |
-| -------- | ----------- |
-| [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker) | Docker provisions a development container. |
-| [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes) | Provisions a development container on the Kubernetes cluster. |
+| Template | Description |
+| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Docker dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker) | Docker provisions a development container. |
+| [Kubernetes dev containers](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes) | Provisions a development container on the Kubernetes cluster. |
| [Google Compute Engine dev container](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer) | Runs a development container inside a single GCP instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
-| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
+| [AWS EC2 dev container](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer) | Runs a development container inside a single EC2 instance. It also mounts the Docker socket from the VM inside the container to enable Docker inside the workspace. |
Your template can prompt the user for a repo URL with
[parameters](../../extending-templates/parameters.md):
From d17dbeae44a429a1c75cc47bbf94a2d4a3a3e325 Mon Sep 17 00:00:00 2001
From: EdwardAngert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:44:05 +0000
Subject: [PATCH 34/36] un-double bullet def list
---
docs/admin/index.md | 99 ++++++++++++++++++++++-----------------------
1 file changed, 49 insertions(+), 50 deletions(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index d4516ba520311..e1f9920514df8 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -17,55 +17,54 @@ For any information not strictly contained in these sections, check out our
## What is an image, template, devcontainer, or workspace
-- **Image**
-
- - A [base image](./templates/managing-templates/image-management.md) contains
- OS-level packages, and utilities that the Coder workspace is built on. It
- can be an [example image](https://github.com/coder/images), custom image in
- your registry, or one from [Docker Hub](https://hub.docker.com/search). It
- is defined in each template.
- - Managed by: Externally to Coder.
-
-- **Template**
-
- - [Templates](./templates/index.md) include infrastructure-level dependencies
- for the workspace. For example, a template can include Kubernetes
- PersistentVolumeClaims, Docker containers, or EC2 VMs.
- - Managed by: Template administrators from within the Coder deployment.
-
-- **Startup scripts**
-
- - Agent startup scripts apply to all users of a template. This is an
- intentionally flexible area that template authors have at their disposal to
- manage the "last mile" of workspace creation.
- - Managed by: Coder template administrators.
-
-- **Workspace**
-
- - A [workspace](../user-guides/workspace-management.md) is the environment
- that a developer works in. Developers on a team each work from their own
- workspace and can use
- [multiple IDEs](../user-guides/workspace-access/index.md).
- - Managed by: Developers
-
-- **Development containers (dev containers)**
-
- - A
- [Development Container](./templates/managing-templates/devcontainers/index.md)
- is an open-source specification for defining development environments
- (called dev containers). It is generally stored in VCS alongside associated
- source code. It can reference an existing base image, or a custom Dockerfile
- that will be built on-demand.
- - Managed by: Dev Teams
-
-- **Dotfiles / personalization**
-
- - Users may have their own specific preferences relating to shell prompt,
- custom keybindings, color schemes, and more. Users can leverage Coder's
- [dotfiles support](../user-guides/workspace-dotfiles.md) or create their own
- script to personalize their workspace. Be aware that users with root
- permissions in their workspace can override almost all of the previous
- configuration.
- - Managed by: Individual Users
+**Image**
+
+- A [base image](./templates/managing-templates/image-management.md) contains
+ OS-level packages, and utilities that the Coder workspace is built on. It can
+ be an [example image](https://github.com/coder/images), custom image in your
+ registry, or one from [Docker Hub](https://hub.docker.com/search). It is
+ defined in each template.
+- Managed by: Externally to Coder.
+
+**Template**
+
+- [Templates](./templates/index.md) include infrastructure-level dependencies
+ for the workspace. For example, a template can include Kubernetes
+ PersistentVolumeClaims, Docker containers, or EC2 VMs.
+- Managed by: Template administrators from within the Coder deployment.
+
+**Startup scripts**
+
+- Agent startup scripts apply to all users of a template. This is an
+ intentionally flexible area that template authors have at their disposal to
+ manage the "last mile" of workspace creation.
+- Managed by: Coder template administrators.
+
+**Workspace**
+
+- A [workspace](../user-guides/workspace-management.md) is the environment that
+ a developer works in. Developers on a team each work from their own workspace
+ and can use [multiple IDEs](../user-guides/workspace-access/index.md).
+- Managed by: Developers
+
+**Development containers (dev containers)**
+
+- A
+ [Development Container](./templates/managing-templates/devcontainers/index.md)
+ is an open-source specification for defining development environments (called
+ dev containers). It is generally stored in VCS alongside associated source
+ code. It can reference an existing base image, or a custom Dockerfile that
+ will be built on-demand.
+- Managed by: Dev Teams
+
+**Dotfiles / personalization**
+
+- Users may have their own specific preferences relating to shell prompt, custom
+ keybindings, color schemes, and more. Users can leverage Coder's
+ [dotfiles support](../user-guides/workspace-dotfiles.md) or create their own
+ script to personalize their workspace. Be aware that users with root
+ permissions in their workspace can override almost all of the previous
+ configuration.
+- Managed by: Individual Users
<children></children>
From 2c3ca6d44fd11d23f1a9b2c736a21dc8f8fc6c23 Mon Sep 17 00:00:00 2001
From: EdwardAngert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:44:54 +0000
Subject: [PATCH 35/36] s/devcontainer/dev container
---
docs/admin/index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index e1f9920514df8..88477aaff3e60 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -15,7 +15,7 @@ and [API](../reference/api/index.md) docs.
For any information not strictly contained in these sections, check out our
[Tutorials](../tutorials/index.md) and [FAQs](../tutorials/faqs.md).
-## What is an image, template, devcontainer, or workspace
+## What is an image, template, dev container, or workspace
**Image**
From c28f16d42b09bbe4227fe935ba452b677214b779 Mon Sep 17 00:00:00 2001
From: EdwardAngert <2408959-EdwardAngert@users.noreply.gitlab.com>
Date: Tue, 26 Nov 2024 19:47:13 +0000
Subject: [PATCH 36/36] comma typo
---
docs/admin/index.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 88477aaff3e60..a1552bcf22b9c 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -20,7 +20,7 @@ For any information not strictly contained in these sections, check out our
**Image**
- A [base image](./templates/managing-templates/image-management.md) contains
- OS-level packages, and utilities that the Coder workspace is built on. It can
+ OS-level packages and utilities that the Coder workspace is built on. It can
be an [example image](https://github.com/coder/images), custom image in your
registry, or one from [Docker Hub](https://hub.docker.com/search). It is
defined in each template.