Skip to content

chore(docs): add explicit documention for parts of devcontainer spec supported by envbuilder #408

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 2 commits into from
Nov 6, 2024
Merged

chore(docs): add explicit documention for parts of devcontainer spec supported by envbuilder #408

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
930ee2b
chore(docs): add explicit documention for parts of devcontainer spec …
johnstcn Nov 6, 2024
f872337
address PR feedback
johnstcn Nov 6, 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
12 changes: 2 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -82,19 +82,11 @@ docker run -it --rm

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

## Unsupported Features

### Development Containers

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.
[This document](./docs/supported-features.md) keeps track of what parts of the Dev Container specification Envbuilder currently supports.

| Name | Description | Known Issues |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| Volume mounts | Volumes are used to persist data and share directories between the host and container. | [#220](https://github.com/coder/envbuilder/issues/220) |
| Port forwarding | Port forwarding allows exposing container ports to the host, making services accessible. | [#48](https://github.com/coder/envbuilder/issues/48) |
| 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) |
| Customizations | Product-specific properties, e.g., _VS Code_ settings and extensions. | [#43](https://github.com/coder/envbuilder/issues/43) |
| Composefile | Define multiple containers and services for more complex development environments. | [#236](https://github.com/coder/envbuilder/issues/236) |
Feel free to [create a new issue](https://github.com/coder/envbuilder/issues/new) if you'd like Envbuilder to support a particular feature.

### Devfile

Expand Down
72 changes: 72 additions & 0 deletions docs/devcontainer-spec-support.md
View file
Open in desktop
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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: can we sort them in lex. order?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I intentionally kept the same ordering as https://containers.dev/implementors/json_reference/

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, let's leave it them. I admit this might be hard to find an interesting item without ctrl+f.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's a big spec!

| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **General** | | |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we present supported features first?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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. | - |
| 🟢 | `containerUser` | Override the user for all operations run inside the container. | - |
| 🔴 | `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. | - |
| 🔴 | `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) |
| **Image/Dockerfile** | | |
| 🟢 | `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. | |
| 🔴 | `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. | - |