Devcontainers

Development containers are an open source specification for defining development environments.

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 when they create their workspace. Envbuilder clones the repo and builds a container from the devcontainer.json specified in the repo.

When using the 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) provisions a development container using Docker.
• Devcontainers (Kubernetes) provisions a development container on the Kubernetes.
• Google Compute Engine (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) 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.

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 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 for more information.

Envbuilder Terraform Provider

To support resuming from a cached image, use the Envbuilder Terraform Provider 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. You may also wish to consult a documented example usage of the envbuilder_cached_image resource.

Other features & known issues

Envbuilder provides two release channels:

• Stable: available at ghcr.io/coder/envbuilder. Tags >=1.0.0 are considered stable.
• Preview: available at ghcr.io/coder/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 for more information and to submit feature requests or bug reports.