diff --git a/docs/admin/index.md b/docs/admin/index.md index 6ef0e6fb65..a1552bcf22 100644 --- a/docs/admin/index.md +++ b/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 + diff --git a/docs/admin/templates/index.md b/docs/admin/templates/index.md index ad9c3ef965..85f2769e88 100644 --- a/docs/admin/templates/index.md +++ b/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). diff --git a/docs/admin/templates/managing-templates/devcontainers.md b/docs/admin/templates/managing-templates/devcontainers.md deleted file mode 100644 index 088f733adc..0000000000 --- a/docs/admin/templates/managing-templates/devcontainers.md +++ /dev/null @@ -1,112 +0,0 @@ -# Dev Containers - -[Development containers](https://containers.dev) are an open source -specification for defining development environments. - -[Envbuilder](https://github.com/coder/envbuilder) is an open source project by -Coder that runs dev containers via Coder templates and your underlying -infrastructure. It can run on Docker or Kubernetes. - -There are several benefits to adding a devcontainer-compatible template to -Coder: - -- Drop-in migration from Codespaces (or any existing repositories that use 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. - -## How it works - -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. - -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. - -Developers can edit the `devcontainer.json` in their workspace to rebuild to -iterate on their development environments. - -## 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. - -![Devcontainer parameter screen](../../../images/templates/devcontainers.png) - -Your template can prompt the user for a repo URL with -[Parameters](../extending-templates/parameters.md). - -## 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. - -## 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). - -Refer to the -[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md) -for more information. - -## Envbuilder Terraform Provider - -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 - Envbuilder would, -3. 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. - -The above example templates 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 - -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**. - -Refer to the [Envbuilder GitHub repo](https://github.com/coder/envbuilder/) for -more information and to submit feature requests or bug reports. 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 0000000000..18dabcf2b2 --- /dev/null +++ b/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): + +
+ +## 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 -d + ``` + + - 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) + +
+ +To set variables such as the namespace, go to the template in your Coder +dashboard and select **Settings** from the **⋮** (vertical ellipsis) menu: + +Choose Settings from the template's menu + +## 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) + +``` + +``` 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 0000000000..b8ba3bfddd --- /dev/null +++ b/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. 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 0000000000..bb56ff6a31 --- /dev/null +++ b/docs/admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md @@ -0,0 +1,66 @@ +# 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. + +### Configure registry authentication + +You may need to authenticate to your container registry, such as Artifactory, or +Git provider such as GitLab, to use Envbuilder. See the +[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md) +for more information. + +## Layer and image caching + +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#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 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. + +### 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 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 + +- [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 new file mode 100644 index 0000000000..a4ec140765 --- /dev/null +++ b/docs/admin/templates/managing-templates/devcontainers/index.md @@ -0,0 +1,122 @@ +# Dev containers + +A Development Container is an +[open-source specification](https://containers.dev/implementors/spec/) for +defining containerized development environments which are also called +development containers (dev containers). + +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. + +## Prerequisites + +An administrator should construct or choose a base image and create a template +that includes a `devcontainer_builder` image before a developer team configures +dev containers. + +## Benefits of devcontainers + +There are several benefits to adding a dev container-compatible template to +Coder: + +- Reliability through standardization +- Scalability for growing teams +- Improved security +- Performance efficiency +- Cost Optimization + +### Reliability through standardization + +Use dev containers to empower development teams to personalize their own +environments while maintaining consistency and security through an approved and +hardened base image. + +Standardized environments ensure uniform behavior across machines and team +members, eliminating "it works on my machine" issues and creating a stable +foundation for development and testing. Containerized setups reduce dependency +conflicts and misconfigurations, enhancing build stability. + +### Scalability for growing teams + +Dev containers allow organizations to handle multiple projects and teams +efficiently. + +You can leverage platforms like Kubernetes to allocate resources on demand, +optimizing costs and ensuring fair distribution of quotas. Developer teams can +use efficient custom images and independently configure the contents of their +version-controlled dev containers. + +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 + +Since Coder and Envbuilder run on your own infrastructure, you can use firewalls +and cluster-level policies to ensure Envbuilder only downloads packages from +your secure registry powered by JFrog Artifactory or Sonatype Nexus. +Additionally, Envbuilder can be configured to push the full image back to your +registry for additional security scanning. + +This means that Coder admins can require hardened base images and packages, +while still allowing developer self-service. + +Envbuilder runs inside a small container image but does not require a Docker +daemon in order to build a dev container. This is useful in environments where +you may not have access to a Docker socket for security reasons, but still need +to work with a container. + +### Performance efficiency + +Create a unique image for each project to reduce the dependency size of any +given project. + +Envbuilder has various caching modes to ensure workspaces start as fast as +possible, such as layer caching and even full image caching and fetching via the +[Envbuilder Terraform provider](https://registry.terraform.io/providers/coder/envbuilder/latest/docs). + +### Cost optimization + +By creating unique images per-project, you remove unnecessary dependencies and +reduce the workspace size and resource consumption of any given project. Full +image caching ensures optimal start and stop times. + +## When to use a dev container + +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. + +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 + +[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](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 +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 dev container 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 e1536be3f0..2f4cf2e43e 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 @@ -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 0abbac6048..a9e215bb71 100644 --- a/docs/admin/templates/managing-templates/index.md +++ b/docs/admin/templates/managing-templates/index.md @@ -91,5 +91,5 @@ coder templates delete ## 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/images/templates/template-menu-settings.png b/docs/images/templates/template-menu-settings.png new file mode 100644 index 0000000000..cac2aca146 Binary files /dev/null and b/docs/images/templates/template-menu-settings.png differ diff --git a/docs/manifest.json b/docs/manifest.json index 40b4a3ed02..14a9a7f5c6 100644 --- a/docs/manifest.json +++ b/docs/manifest.json @@ -321,9 +321,26 @@ "path": "./admin/templates/managing-templates/change-management.md" }, { - "title": "Devcontainers", - "description": "Learn about using devcontainers in templates", - "path": "./admin/templates/managing-templates/devcontainers.md" + "title": "Dev containers", + "description": "Learn about using development containers in templates", + "path": "./admin/templates/managing-templates/devcontainers/index.md", + "children": [ + { + "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": "Dev container security and caching", + "description": "Configure dev container authentication and caching", + "path": "./admin/templates/managing-templates/devcontainers/devcontainer-security-caching.md" + }, + { + "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" + } + ] }, { "title": "Template Dependencies",