Skip to content

Commit 62047e5

Browse files
johnstcnjohnstcn
authored
chore(docs): update devcontainer docs (coder#14850)
Fixes coder/envbuilder#131
1 parent 3b5cabb commit 62047e5

File tree

3 files changed

+69
-19
lines changed

3 files changed

+69
-19
lines changed

‎docs/architecture/architecture.md

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -346,9 +346,6 @@ across multiple regions and diverse cloud platforms.
346346

347347
### Dev Containers
348348

349-
Note: _Dev containers_ are at early stage and considered experimental at the
350-
moment.
351-
352349
This architecture enhances a Coder workspace with a
353350
[development container](https://containers.dev/) setup built using the
354351
[envbuilder](https://github.com/coder/envbuilder) project. Workspace users have

‎docs/manifest.json

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -271,8 +271,7 @@
271271
{
272272
"title": "Dev Containers",
273273
"description": "Use Dev Containers in workspaces",
274-
"path": "./templates/dev-containers.md",
275-
"state": "alpha"
274+
"path": "./templates/dev-containers.md"
276275
},
277276
{
278277
"title": "Troubleshooting templates",

‎docs/templates/dev-containers.md

Lines changed: 68 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
1-
# Dev Containers (alpha)
1+
# Dev Containers
22

33
[Development containers](https://containers.dev) are an open source
44
specification for defining development environments.
55

6-
[envbuilder](https://github.com/coder/envbuilder) is an open source project by
6+
[Envbuilder](https://github.com/coder/envbuilder) is an open source project by
77
Coder that runs dev containers via Coder templates and your underlying
88
infrastructure. It can run on Docker or Kubernetes.
99

@@ -22,16 +22,30 @@ Coder:
2222
A Coder admin adds a devcontainer-compatible template to Coder (envbuilder).
2323
Then developers enter their repository URL as a [parameter](./parameters.md)
2424
when they create their workspace.
25-
[envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a
25+
[Envbuilder](https://github.com/coder/envbuilder) clones the repo and builds a
2626
container from the `devcontainer.json` specified in the repo.
2727

28+
When using the [Envbuilder Terraform provider](#provider), a previously built
29+
and cached image can be re-used directly, allowing instantaneous dev container
30+
starts.
31+
2832
Developers can edit the `devcontainer.json` in their workspace to rebuild to
2933
iterate on their development environments.
3034

3135
## Example templates
3236

33-
- [Docker](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
34-
- [Kubernetes](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
37+
- [Devcontainers (Docker)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-docker)
38+
provisions a development container using Docker.
39+
- [Devcontainers (Kubernetes)](https://github.com/coder/coder/tree/main/examples/templates/devcontainer-kubernetes)
40+
provisioners a development container on the Kubernetes.
41+
- [Google Compute Engine (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/gcp-devcontainer)
42+
runs a development container inside a single GCP instance. It also mounts the
43+
Docker socket from the VM inside the container to enable Docker inside the
44+
workspace.
45+
- [AWS EC2 (Devcontainer)](https://github.com/coder/coder/tree/main/examples/templates/aws-devcontainer)
46+
runs a development container inside a single EC2 instance. It also mounts the
47+
Docker socket from the VM inside the container to enable Docker inside the
48+
workspace.
3549

3650
![Devcontainer parameter screen](../images/templates/devcontainers.png)
3751

@@ -41,18 +55,58 @@ Your template can prompt the user for a repo URL with
4155
## Authentication
4256

4357
You may need to authenticate to your container registry, such as Artifactory, or
44-
git provider such as GitLab, to use envbuilder. See the
45-
[envbuilder documentation](https://github.com/coder/envbuilder/) for more
46-
information.
58+
git provider such as GitLab, to use Envbuilder. See the
59+
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/container-registry-auth.md)
60+
for more information.
4761

4862
## Caching
4963

50-
To improve build times, dev containers can be cached. Refer to the
51-
[envbuilder documentation](https://github.com/coder/envbuilder/) for more
52-
information.
64+
To improve build times, dev containers can be cached. There are two main forms
65+
of caching:
66+
67+
1. **Layer Caching** caches individual layers and pushes them to a remote
68+
registry. When building the image, Envbuilder will check the remote registry
69+
for pre-existing layers. These will be fetched and extracted to disk instead
70+
of building the layers from scratch.
71+
2. **Image Caching** caches the _entire image_, skipping the build process
72+
completely (except for post-build lifecycle scripts).
73+
74+
Refer to the
75+
[Envbuilder documentation](https://github.com/coder/envbuilder/blob/main/docs/caching.md)
76+
for more information.
77+
78+
## Envbuilder Terraform Provider
79+
80+
To support resuming from a cached image, use the
81+
[Envbuilder Terraform Provider](https://github.com/coder/terraform-provider-envbuilder)
82+
in your template. The provider will:
83+
84+
1. Clone the remote Git repository,
85+
2. Perform a 'dry-run' build of the dev container in the same manner as
86+
Envbuilder would,
87+
3. Check for the presence of a previously built image in the provided cache
88+
repository,
89+
4. Output the image remote reference in SHA256 form, if found.
90+
91+
The above example templates will use the provider if a remote cache repository
92+
is provided.
93+
94+
If you are building your own Devcontainer template, you can consult the
95+
[provider documentation](https://registry.terraform.io/providers/coder/envbuilder/latest/docs/resources/cached_image).
96+
You may also wish to consult a
97+
[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).
5398

5499
## Other features & known issues
55100

56-
Envbuilder is still under active development. Refer to the
57-
[envbuilder GitHub repo](https://github.com/coder/envbuilder/) for more
58-
information and to submit feature requests.
101+
Envbuilder provides two release channels:
102+
103+
- **Stable:** available at
104+
[`ghcr.io/coder/envbuilder`](https://github.com/coder/envbuilder/pkgs/container/envbuilder).
105+
Tags `>=1.0.0` are considered stable.
106+
- **Preview:** available at
107+
[`ghcr.io/coder/envbuilder-preview`](https://github.com/coder/envbuilder/pkgs/container/envbuilder-preview).
108+
This is built from the tip of `main`, and should be considered
109+
**experimental** and prone to **breaking changes**.
110+
111+
Refer to the [Envbuilder GitHub repo](https://github.com/coder/envbuilder/) for
112+
more information and to submit feature requests or bug reports.

0 commit comments

Comments
 (0)