chore(docs): add explicit documention for parts of devcontainer spec supported by envbuilder #408
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| # Support for Dev Container Specification | ||
|
|
||
| > Refer to the full Dev Container specification [here](https://containers.dev/implementors/json_reference/) for more information on the below options. | ||
|
|
||
| The symbols in the first column indicate the support status: | ||
|
|
||
| - 🟢 Fully supported. | ||
| - 🟠 Partially supported. | ||
| - 🔴 Not currently supported. | ||
|
|
||
| The last column indicates any currently existing GitHub issue for tracking support for this feature. | ||
| Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature. | ||
|
|
||
| | Status | Name | Description | Known Issues | | ||
|
There was a problem hiding this comment. nit: can we sort them in lex. order? There was a problem hiding this comment. I intentionally kept the same ordering as https://containers.dev/implementors/json_reference/ There was a problem hiding this comment. Ok, let's leave it them. I admit this might be hard to find an interesting item without ctrl+f. |
||
| | ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | ||
| | **General** | | | | ||
|
There was a problem hiding this comment. should we present supported features first? There was a problem hiding this comment. I'm going to punt on ordering for now as it's fairly easy to change in a separate PR. |
||
| | 🔴 | `name` | Human-friendly name for the dev container. | - | | ||
| | 🔴 | `forwardPorts` | Port forwarding allows exposing container ports to the host, making services accessible. | [#48](https://github.com/coder/envbuilder/issues/48) | | ||
| | 🔴 | `portsAttributes` | Set port attributes for a `host:port`. | - | | ||
| | 🔴 | `otherPortsAttributes` | Other options for ports not configured using `portsAttributes`. | - | | ||
| | 🟢 | `containerEnv` | Environment variables to set inside the container. | - | | ||
| | 🟢 | `remoteEnv` | Override environment variables for specific supporting services or tools, but not the container as a whole. | - | | ||
| | 🟢 | `remoteUser` | Override the user that supporting tools run as inside the container without changing the user for the whole container. | - | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 🟢 | `containerUser` | Override the user for all operations run inside the container. | - | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 🔴 | `updateRemoteUserUID` | Update the devcontainer UID/GID to match the local user. | - | | ||
| | 🔴 | `userEnvProbe` | Shell to use when probing for user environment variables. | - | | ||
| | 🔴 | `overrideCommand` | Override the default sleep command to be run by supporting services. | - | | ||
| | 🔴 | `shutdownAction` | Action to take when supporting tools are closed or shut down. | - | | ||
| | 🔴 | `init` | Adds a tiny init process to the container. | [#221](https://github.com/coder/envbuilder/issues/221) | | ||
| | 🔴 | `privileged` | Whether the container should be run in privileged mode. | - | | ||
| | 🔴 | `capAdd` | Capabilities to add to the container (for example, `SYS_PTRACE`). | - | | ||
| | 🔴 | `securityOpt` | Security options to add to the container (for example, `seccomp=unconfined`). | - | | ||
| | 🔴 | `mounts` | Add additional mounts to the container. | [#220](https://github.com/coder/envbuilder/issues/220) | | ||
| | 🟢 | `features` | Features to be added to the devcontainer. | - | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 🔴 | `overrideFeatureInstallOrder` | Override the order in which features should be installed. | [#226](https://github.com/coder/envbuilder/issues/226) | | ||
| | 🔴 | `customizations` | Product-specific properties, e.g., _VS Code_ settings and extensions. | [#43](https://github.com/coder/envbuilder/issues/43) | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | **Image/Dockerfile** | | | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 🟢 | `image` | Name of an image to run. | - | | ||
| | 🟢 | `build.dockerfile` | Path to a Dockerfile to build relative to `devcontainer.json`. | - | | ||
| | 🟢 | `build.context` | Path to the build context relative to `devcontainer.json`. | - | | ||
| | 🟢 | `build.args` | Build args to use when building the Dockerfile. | - | | ||
| | 🔴 | `build.options` | Build options to pass to the Docker daemon. Envbuilder does not use a Docker daemon, so this is not relevant. | - | | ||
| | 🟢 | `build.target` | Target to be passed when building the Dockerfile. | - | | ||
| | 🟢 | `build.cacheFrom` | Images to use as caches when building the Dockerfile. | - | | ||
| | 🔴 | `appPort` | Ports to be published locally when the container is running. | - | | ||
| | 🔴 | `workspaceMount` | Overrides the default local mount point for the workspace when the container is created. | - | | ||
| | 🔴 | `workspaceFolder` | Default path to open when connecting to the container. | - | | ||
| | **Docker Compose** | | | | ||
| | 🔴 | `dockerComposeFile` | Path to a Docker Compose file related to the `devcontainer.json`. | [#236](https://github.com/coder/envbuilder/issues/236) | | ||
| | 🔴 | `service` | Name of the Docker Compose service to which supporting tools should connect. | [#236](https://github.com/coder/envbuilder/issues/236) | | ||
| | 🔴 | `runServices` | Docker Compose services to automatically start. | [#236](https://github.com/coder/envbuilder/issues/236) | | ||
| | **Lifecycle scripts** | | | | ||
| | 🔴 | `initializeCommand` | Command to run on the host machine when creating the container. | [#395](https://github.com/coder/envbuilder/issues/395) | | ||
| | 🟢 | `onCreateCommand` | Command to run inside container after first start. | | | ||
| | 🟢 | `updateContentCommand` | Command to run after `onCreateCommand` inside container. | | | ||
| | 🟢 | `postCreateCommand` | Command to run after `updateContentCommand` inside container. | | | ||
| | 🟢 | `postStartCommand` | Command to run each time the container is started. | | | ||
johnstcn marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| | 🔴 | `postAttachCommand` | Command to run each time a tool attaches to the container. | | | ||
| | 🔴 | `waitFor` | Specify the lifecycle command tools should wait to complete before connecting. | | | ||
| | **Minimum Host Requirements** | | | | ||
| | 🔴 | `hostRequirements.cpus` | Minimum number of CPUs required. | - | | ||
| | 🔴 | `hostRequirements.memory` | Minimum memory requirements. | - | | ||
| | 🔴 | `hostRequirements.storage` | Minimum storage requirements. | - | | ||
| | 🔴 | `hostRequirements.gpu` | Whether a GPU is required. | - | | ||
| | **Variable Substitution** | | | | ||
| | 🟢 | `${localEnv:VARIABLE_NAME}` | Environment variable on the host machine. | - | | ||
| | 🟢 | `${containerEnv:VARIABLE_NAME}` | Existing environment variable inside the container. | - | | ||
| | 🟢 | `${localWorkspaceFolder}` | Path to the local workspace folder. | - | | ||
| | 🟢 | `${containerWorkspaceFolder}` | Path to the workspace folder inside the container. | - | | ||
| | 🟢 | `${localWorkspaceFolderBasename}` | Base name of `localWorkspaceFolder`. | - | | ||
| | 🟢 | `${containerWorkspaceFolderBasename}` | Base name of `containerWorkspaceFolder`. | - | | ||
| | 🔴 | `${devcontainerId}` | A stable unique identifier for the devcontainer. | - | | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.