Skip to content

Commit 74695f9

Browse files
johnstcnjohnstcn
authored
chore(docs): add explicit documention for parts of devcontainer spec supported by envbuilder (#408)
1 parent b18cd0e commit 74695f9

File tree

3 files changed

+128
-10
lines changed

3 files changed

+128
-10
lines changed

‎README.md

+2-10
Original file line numberDiff line numberDiff line change
@@ -82,19 +82,11 @@ docker run -it --rm
8282

8383
You can see all the supported environment variables in [this document](./docs/env-variables.md).
8484

85-
## Unsupported Features
86-
8785
### Development Containers
8886

89-
The table below keeps track of features we plan to implement. Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature.
87+
[This document](./docs/devcontainer-spec-support.md) keeps track of what parts of the Dev Container specification Envbuilder currently supports.
9088

91-
| Name | Description | Known Issues |
92-
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
93-
| Volume mounts | Volumes are used to persist data and share directories between the host and container. | [#220](https://github.com/coder/envbuilder/issues/220) |
94-
| Port forwarding | Port forwarding allows exposing container ports to the host, making services accessible. | [#48](https://github.com/coder/envbuilder/issues/48) |
95-
| Script init & Entrypoint | `init` adds a tiny init process to the container, and `entrypoint` sets a script to run at container startup. | [#221](https://github.com/coder/envbuilder/issues/221) |
96-
| Customizations | Product-specific properties, e.g., _VS Code_ settings and extensions. | [#43](https://github.com/coder/envbuilder/issues/43) |
97-
| Composefile | Define multiple containers and services for more complex development environments. | [#236](https://github.com/coder/envbuilder/issues/236) |
89+
Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature.
9890

9991
### Devfile
10092

‎docs/devcontainer-spec-support.md

+123
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Support for Dev Container Specification
2+
3+
> Refer to the full Dev Container specification [here](https://containers.dev/implementors/json_reference/) for more information on the below options.
4+
5+
The symbols in the first column indicate the support status:
6+
7+
- 🟢 Fully supported.
8+
- 🟠 Partially supported.
9+
- 🔴 Not currently supported.
10+
11+
The last column indicates any currently existing GitHub issue for tracking support for this feature.
12+
Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature.
13+
14+
## General
15+
16+
| Status | Name | Description | Known Issues |
17+
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
18+
| 🔴 | `name` | Human-friendly name for the dev container. | - |
19+
| 🔴 | `forwardPorts` | Port forwarding allows exposing container ports to the host, making services accessible. | [#48](https://github.com/coder/envbuilder/issues/48) |
20+
| 🔴 | `portsAttributes` | Set port attributes for a `host:port`. | - |
21+
| 🔴 | `otherPortsAttributes` | Other options for ports not configured using `portsAttributes`. | - |
22+
| 🟢 | `containerEnv` | Environment variables to set inside the container. | - |
23+
| 🟢 | `remoteEnv` | Override environment variables for tools, but not the whole container. | - |
24+
| 🟢\* | `remoteUser` | Override the user for tools, but not the whole container. <br/>\*_Refer to [choosing a target user](./users.md#choosing-a-target-user), as behaviour may diverge from the spec._ | - |
25+
| 🟢\* | `containerUser` | Override the user for all operations run inside the container. <br/>\*_Refer to [choosing a target user](./users.md#choosing-a-target-user), as behaviour may diverge from the spec._ | - |
26+
| 🔴 | `updateRemoteUserUID` | Update the devcontainer UID/GID to match the local user. | - |
27+
| 🔴 | `userEnvProbe` | Shell to use when probing for user environment variables. | - |
28+
| 🔴 | `overrideCommand` | Override the default sleep command to be run by supporting services. | - |
29+
| 🔴 | `shutdownAction` | Action to take when supporting tools are closed or shut down. | - |
30+
| 🔴 | `init` | Adds a tiny init process to the container. | [#221](https://github.com/coder/envbuilder/issues/221) |
31+
| 🔴 | `privileged` | Whether the container should be run in privileged mode. | - |
32+
| 🔴 | `capAdd` | Capabilities to add to the container (for example, `SYS_PTRACE`). | - |
33+
| 🔴 | `securityOpt` | Security options to add to the container (for example, `seccomp=unconfined`). | - |
34+
| 🔴 | `mounts` | Add additional mounts to the container. | [#220](https://github.com/coder/envbuilder/issues/220) |
35+
| 🟢 | `features` | Features to be added to the devcontainer. | - |
36+
| 🔴 | `overrideFeatureInstallOrder` | Override the order in which features should be installed. | [#226](https://github.com/coder/envbuilder/issues/226) |
37+
| 🟠 | `customizations` | Product-specific properties, e.g., _VS Code_ settings and extensions. | Workaround in [#43](https://github.com/coder/envbuilder/issues/43) |
38+
39+
## Image or Dockerfile
40+
41+
| Status | Name | Description | Known Issues |
42+
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------- | ------------ |
43+
| 🟢 | `image` | Name of an image to run. | - |
44+
| 🟢 | `build.dockerfile` | Path to a Dockerfile to build relative to `devcontainer.json`. | - |
45+
| 🟢 | `build.context` | Path to the build context relative to `devcontainer.json`. | - |
46+
| 🟢 | `build.args` | Build args to use when building the Dockerfile. | - |
47+
| 🔴 | `build.options` | Build options to pass to the Docker daemon. Envbuilder does not use a Docker daemon, so this is not relevant. | - |
48+
| 🟢 | `build.target` | Target to be passed when building the Dockerfile. | - |
49+
| 🟢 | `build.cacheFrom` | Images to use as caches when building the Dockerfile. | - |
50+
| 🔴 | `appPort` | Ports to be published locally when the container is running. | - |
51+
| 🔴 | `workspaceMount` | Overrides the default local mount point for the workspace when the container is created. | - |
52+
| 🔴 | `workspaceFolder` | Default path to open when connecting to the container. | - |
53+
54+
## Docker Compose
55+
56+
| Status | Name | Description | Known Issues |
57+
| ------ | ------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------ |
58+
| 🔴 | `dockerComposeFile` | Path to a Docker Compose file related to the `devcontainer.json`. | [#236](https://github.com/coder/envbuilder/issues/236) |
59+
| 🔴 | `service` | Name of the Docker Compose service to which supporting tools should connect. | [#236](https://github.com/coder/envbuilder/issues/236) |
60+
| 🔴 | `runServices` | Docker Compose services to automatically start. | [#236](https://github.com/coder/envbuilder/issues/236) |
61+
62+
## Lifecycle Scripts
63+
64+
| Status | Name | Description | Known Issues |
65+
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
66+
| 🔴 | `initializeCommand` | Command to run on the host machine when creating the container. | [#395](https://github.com/coder/envbuilder/issues/395) |
67+
| 🟢 | `onCreateCommand` | Command to run inside container after first start. | |
68+
| 🟢 | `updateContentCommand` | Command to run after `onCreateCommand` inside container. | |
69+
| 🟢 | `postCreateCommand` | Command to run after `updateContentCommand` inside container. | |
70+
| 🟢\* | `postStartCommand` | Command to run each time the container is started.<br/>\*_This may be specified by `ENVBUILDER_POST_START_SCRIPT`, in which case it is the responsibility of `ENVBUILDER_INIT_COMMAND` to run it._ | |
71+
| 🔴 | `postAttachCommand` | Command to run each time a tool attaches to the container. | |
72+
| 🔴 | `waitFor` | Specify the lifecycle command tools should wait to complete before connecting. | |
73+
74+
## Minimum Host Requirements
75+
76+
| Status | Name | Description | Known Issues |
77+
| ------ | -------------------------- | -------------------------------- | ------------ |
78+
| 🔴 | `hostRequirements.cpus` | Minimum number of CPUs required. | - |
79+
| 🔴 | `hostRequirements.memory` | Minimum memory requirements. | - |
80+
| 🔴 | `hostRequirements.storage` | Minimum storage requirements. | - |
81+
| 🔴 | `hostRequirements.gpu` | Whether a GPU is required. | - |
82+
83+
## Variable Substitution
84+
85+
| Status | Name | Description | Known Issues |
86+
| ------ | ------------------------------------- | --------------------------------------------------- | ------------ |
87+
| 🟢 | `${localEnv:VARIABLE_NAME}` | Environment variable on the host machine. | - |
88+
| 🟢 | `${containerEnv:VARIABLE_NAME}` | Existing environment variable inside the container. | - |
89+
| 🟢 | `${localWorkspaceFolder}` | Path to the local workspace folder. | - |
90+
| 🟢 | `${containerWorkspaceFolder}` | Path to the workspace folder inside the container. | - |
91+
| 🟢 | `${localWorkspaceFolderBasename}` | Base name of `localWorkspaceFolder`. | - |
92+
| 🟢 | `${containerWorkspaceFolderBasename}` | Base name of `containerWorkspaceFolder`. | - |
93+
| 🔴 | `${devcontainerId}` | A stable unique identifier for the devcontainer. | - |
94+
95+
## Features
96+
97+
| Status | Name | Description | Known Issues |
98+
| ------ | ------------------------ | ------------------------------------------------------------ | ------------ |
99+
| 🟢 | `id` | Feature identifier | - |
100+
| � | `version` | Feature version | - |
101+
| 🟢 | `name` | Feature version | - |
102+
| 🟢 | `description` | Description | - |
103+
| 🟢 | `documentationURL` | Feature documentation URL | - |
104+
| 🟢 | `licenseURL` | Feature license URL | - |
105+
| 🟢 | `keywords` | Feature keywords | - |
106+
| 🟢 | `options` | Map of options passed to the feature | - |
107+
| 🟢 | `options[*].type` | Types of the option | - |
108+
| 🟢 | `options[*].proposals` | Suggested values of the option | - |
109+
| 🟢 | `options[*].enum` | Allowed string values of the option | - |
110+
| 🟢 | `options[*].default` | Default value of the option | - |
111+
| 🟢 | `options[*].description` | Description of the option | - |
112+
| 🟢 | `containerEnv` | Environment variables to override | - |
113+
| 🔴 | `privileged` | Set privileged mode for the container if the feature is used | - |
114+
| 🔴 | `init` | Add `tiny init` when the feature is used | - |
115+
| 🔴 | `capAdd` | Capabilities to add when the feature is used | - |
116+
| 🔴 | `securityOpt` | Security options to add when the feature is used | - |
117+
| 🔴 | `entrypoint` | Override entrypoint when the feature is used | - |
118+
| 🔴 | `customizations` | Product-specific properties to add when the feature is used | - |
119+
| 🔴 | `dependsOn` | Define a hard dependency on other features | - |
120+
| 🔴 | `installsAfter` | Define a soft dependency on other features | - |
121+
| 🔴 | `legacyIds` | Used when renaming a feature | - |
122+
| 🔴 | `deprecated` | Whether the feature is deprecated | - |
123+
| 🔴 | `mounts` | Cross-orchestrator mounts to add to the container | - |

‎docs/users.md

+3
Original file line numberDiff line numberDiff line change
@@ -7,3 +7,6 @@ Envbuilder always expects to be run as `root` in its container, as building an i
77
Envbuilder will first attempt to switch to the `containerUser` defined `devcontainer.json`.
88
If this is not specified, it will look up the last `USER` directive from the specified `Dockerfile` or image.
99
If no alternative user is specified, Envbuilder will fallback to `root`.
10+
11+
When installing Devcontainer Features, Envbuilder will add a directive `USER ${remoteUser}` directive directly after the feature installation directives.
12+
If `remoteUser` is not defined, it will default to `containerUser`.

0 commit comments

Comments
 (0)