Skip to content

chore(docs): update devcontainer docs #14850

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Sep 27, 2024
Merged

chore(docs): update devcontainer docs #14850

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e2f8f51
chore(docs): update devcontainer docs
johnstcn Sep 27, 2024
be0541f
fixup! chore(docs): update devcontainer docs
johnstcn Sep 27, 2024
d8fa0bb
fixup! chore(docs): update devcontainer docs
johnstcn Sep 27, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions docs/architecture/architecture.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -346,9 +346,6 @@ across multiple regions and diverse cloud platforms.

### Dev Containers

Note: _Dev containers_ are at early stage and considered experimental at the
moment.

This architecture enhances a Coder workspace with a
[development container](https://containers.dev/) setup built using the
[envbuilder](https://github.com/coder/envbuilder) project. Workspace users have
Expand Down
3 changes: 1 addition & 2 deletions docs/manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -271,8 +271,7 @@
{
"title": "Dev Containers",
"description": "Use Dev Containers in workspaces",
"path": "./templates/dev-containers.md",
"state": "alpha"
"path": "./templates/dev-containers.md"
},
{
"title": "Troubleshooting templates",
Expand Down
82 changes: 68 additions & 14 deletions docs/templates/dev-containers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# Dev Containers (alpha)
# 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
[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.

Expand All @@ -22,16 +22,30 @@ Coder:
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
Then developers enter their repository URL as a [parameter](./parameters.md)
when they create their workspace.
[envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a
[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](#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

- [Docker](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
- [Kubernetes](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
- [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)
provisioners 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)

Expand All @@ -41,18 +55,58 @@ Your template can prompt the user for a repo URL with
## 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/) for more
information.
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. Refer to the
[envbuilder documentation](https://github.com/coder/envbuilder/) for more
information.
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 is still under active development. Refer to the
[envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more
information and to submit feature requests.
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.
Loading