diff --git a/docs/admin/index.md b/docs/admin/index.md index 6ef0e6fb6541a..a1552bcf22b9c 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 ad9c3ef965592..85f2769e880bd 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 088f733adceb3..0000000000000 --- 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 0000000000000..18dabcf2b23b3 --- /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 0000000000000..b8ba3bfddd21e --- /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 0000000000000..bb56ff6a31e32 --- /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 0000000000000..a4ec140765a4c --- /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 e1536be3f0adb..2f4cf2e43e4cb 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 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 ## 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 0000000000000..cac2aca1462c0 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 40b4a3ed02ad7..14a9a7f5c6279 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", pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy