docs: improve dev containers documentation for user start-up

docs/admin/index.md

@@ -15,4 +15,56 @@ 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, dev container, 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
+
 <children></children>

docs/admin/templates/index.md

@@ -48,8 +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.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).

docs/admin/templates/managing-templates/devcontainers/add-devcontainer.md

@@ -0,0 +1,150 @@
+# 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.
+
+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):
+
+<div class="tabs">
+
+## Dashboard
+
+1. In the Coder dashboard, select **Templates** then **Create Template**.
+1. Use a
+   [starter template](https://github.com/coder/coder/tree/main/examples/templates)
+   or create a new template:
+
+   - 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
+
+1. Use the `template init` command to initialize your choice of image:
+
+   ```shell
+   coder template init --id devcontainer-kubernetes
+   ```
+
+   A list of available templates is shown in the
+   [templates_init](../../../../reference/cli/templates.md) reference.
+
+1. `cd` into the directory and push the template to your Coder deployment:
+
+   ```shell
+   cd devcontainer-kubernetes && 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) 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 templates push <template-name> -d <path to folder containing main.tf>
+   ```
+
+   - 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**:
+
+      ![Upload template](../../../../images/templates/upload-create-your-first-template.png)
+
+   1. Drag the `.zip` file into the **Upload template** section and fill out the
+      details, then select **Create template**.
+
+      ![Upload the template files](../../../../images/templates/upload-create-template-form.png)
+
+</div>
+
+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
+
+When using the
+[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.
+
+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
+
+| 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):
+
+![Dev container parameter screen](../../../../images/templates/devcontainers.png)
+
+## Dev container 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
+
+- [Dev container security and caching](./devcontainer-security-caching.md)
+
+```
+
+```

docs/admin/templates/managing-templates/devcontainers/devcontainer-releases-known-issues.md

@@ -0,0 +1,25 @@
+# Dev container 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
+
+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.