`"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]` | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} + +(**) The ID must refer to either a Feature (1) published to an OCI registry, (2) a Feature Tgz URI, or (3) a Feature in the local file tree. Deprecated Feature identifiers (i.e GitHub Release) are not supported and the presence of this property may be considered a fatal error or ignored. For [local Features (ie: during development)](../features-distribution#addendum-locally-referenced), you may also depend on other local Features by providing a relative path to the Feature, relative to folder containing the active `devcontainer.json`. This behavior of Features within this property again mirror the `features` object in `devcontainer.json`. ### Lifecycle Hooks @@ -70,9 +73,9 @@ The following lifecycle hooks may be declared as properties of `devcontainer-fea | `postCreateCommand` | [string, array, object](/implementors/json_reference#formatting-string-vs-array-properties)| | `postStartCommand` | [string, array, object](/implementors/json_reference#formatting-string-vs-array-properties) | | `postAttachCommand` | [string, array, object](/implementors/json_reference#formatting-string-vs-array-properties) | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} -#### Behavior +#### Behavior Each property mirrors the behavior of the matching property in [`devcontainer.json`](/implementors/json_reference#Lifecycle-scripts), including the behavior that commands are executed from the context of the [project workspace folder](/implementors/spec/#project-workspace-folder). @@ -80,7 +83,41 @@ For each lifecycle hook (in [Feature installation order](/implementors/features/ If a Feature provides a given command with the [object syntax](/implementors/json_reference#formatting-string-vs-array-properties), all commands within that group are executed in parallel, but still blocking commands from subsequent Features and/or the `devcontainer.json`. -> NOTE: These properties are stored within [image metadata](/implementors/spec/#merge-logic). +> **Note**: These properties are stored within [image metadata](/implementors/spec/#merge-logic). + +#### Writing scripts to known container path + +It may be helpful for a Feature to write scripts to a known, persistent path within the container (i.e. for later use in a given lifecycle hook). + +Take for instance the `git-lfs` Feature, which [writes a script](https://github.com/devcontainers/features/blob/4fca96b5e8a4bfc93679098cb19d73c65ce571eb/src/git-lfs/install.sh#L190-L216) to `/usr/local/share/pull-git-lfs-artifacts.sh` during installation. + +##### install.sh +```bash +PULL_GIT_LFS_SCRIPT_PATH="/usr/local/share/pull-git-lfs-artifacts.sh" + +tee "$PULL_GIT_LFS_SCRIPT_PATH" > /dev/null \ +<< EOF +#!/bin/sh +set -e +<...truncated...> +EOF +``` + +This script is then executed during the [`postCreateCommand` lifecycle hook](https://github.com/devcontainers/features/blob/4fca96b5e8a4bfc93679098cb19d73c65ce571eb/src/git-lfs/devcontainer-feature.json#L23). + +##### devcontainer-feature.json +```jsonc +{ + "id": "git-lfs", + "version": "1.1.0", + "name": "Git Large File Support (LFS)", + // <...truncated...> + "postCreateCommand": "/usr/local/share/pull-git-lfs-artifacts.sh", + "installsAfter": [ + "ghcr.io/devcontainers/features/common-utils" + ] +} +``` ### The `options` property @@ -107,7 +144,7 @@ The options property contains a map of option IDs and their related configuratio | `optionId.enum` | array | A strict list of allowed string values. Free-form values are **not** allowed. Omit when using `optionId.proposals`. | | `optionId.default` | string or boolean | Default value for the option. | | `optionId.description` | string | Description for the option. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} ### User environment variables @@ -117,11 +154,11 @@ Feature scripts run as the `root` user and sometimes need to know which user acc Additionally, the home folders of the two users are passed to the Feature scripts as `_REMOTE_USER_HOME` and `_CONTAINER_USER_HOME` environment variables. -The container user can be set with `containerUser` in the devcontainer.json and image metadata, `user` in the docker-compose.yml, `USER` in the Dockerfile, and can be passed down from the base image. +The container user can be set with `containerUser` in the `devcontainer.json` and image metadata, `user` in the `docker-compose.yml`, `USER` in the Dockerfile, and can be passed down from the base image. ### Dev Container ID -An identifier will be referred to as `${devcontainerId}` in the devcontainer.json and the Feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the Feature metadata are: `entrypoint`, `mounts`, `customizations`. +An identifier will be referred to as `${devcontainerId}` in the `devcontainer.json` and the Feature metadata and that will be replaced with the dev container's id. It should only be used in parts of the configuration and metadata that is not used for building the image because that would otherwise prevent pre-building the image at a time when the dev container's id is not known yet. Excluding boolean, numbers and enum properties the properties supporting `${devcontainerId}` in the Feature metadata are: `entrypoint`, `mounts`, `customizations`. Implementations can choose how to compute this identifier. They must ensure that it is unique among other dev containers on the same Docker host and that it is stable across rebuilds of dev containers. The identifier must only contain alphanumeric characters. We describe a way to do this below. @@ -218,7 +255,7 @@ As a shorthand, the value of the `features` property can be provided as a single } ``` -### Referencing a feature +### Referencing a Feature The `id` format specified dicates how a supporting tool will locate and download a given feature. `id` is one of the following: @@ -227,7 +264,7 @@ The `id` format specified dicates how a supporting tool will locate and download | `
`ghcr.io/user/repo/go:1`
`ghcr.io/user/repo/go:latest`| | `https://
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose). | | `init` 🏷️ | boolean | Defaults to `false`. Cross-orchestrator way to indicate whether the [tini init process](https://github.com/krallin/tini) should be used to help deal with zombie processes. | -| `privileged` 🏷️ | boolean | Defaults to `false`. Cross-orchestrator way to cause the container to run in priviledged mode (`--priviledged`). Required for things like Docker-in-Docker, but has security implications particularly when running directly on Linux. | +| `privileged` 🏷️ | boolean | Defaults to `false`. Cross-orchestrator way to cause the container to run in privileged mode (`--privileged`). Required for things like Docker-in-Docker, but has security implications particularly when running directly on Linux. | | `capAdd` 🏷️ | array | Defaults to `[]`. Cross-orchestrator way to add capabilities typically disabled for a container. Most often used to add the `ptrace` capability required to debug languages like C++, Go, and Rust. For example:
`"capAdd": ["SYS_PTRACE"]` | | `securityOpt` 🏷️ | array | Defaults to `[]`. Cross-orchestrator way to set container security options. For example:
`"securityOpt": [ "seccomp=unconfined" ]` | | `mounts` 🏷️ | string or object | Defaults to unset. Cross-orchestrator way to add additional mounts to a container. Each value is a string that accepts the same values as the [Docker CLI `--mount` flag](https://docs.docker.com/engine/reference/commandline/run/#mount). Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the value. For example:
`"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]` | | `features` | object | An object of [Dev Container Feature IDs](../../features) and related options to be added into your primary container. The specific options that are available varies by feature, so see its documentation for additional details. For example:
`"features": { "ghcr.io/devcontainers/features/github-cli": {} }` | -| `overrideFeatureInstallOrder` | array | By default, Features will attempt to automatically set the order they are installed based on a `installsAfter` property within each of them. This property allows you to override the Feature install order when needed. For example:
`"overrideFeatureInstallorder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ]` | -| `customizations` 🏷️ | object | Product specific properties, defined in [supporting tools](../../supporting) | -{: .table .table-bordered .table-responsive} +| `overrideFeatureInstallOrder` | array | By default, Features will attempt to automatically set the order they are installed based on a `installsAfter` property within each of them. This property allows you to override the Feature install order when needed. For example:
`"overrideFeatureInstallОrder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ]` | +| `customizations` 🏷️| object | Product specific properties, defined in [supporting tools](../../supporting) | +{: .table .table-bordered} ## Scenario specific properties @@ -48,23 +48,24 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `build.dockerfile` | string |**Required** when using a Dockerfile. The location of a [Dockerfile](https://docs.docker.com/engine/reference/builder/) that defines the contents of the container. The path is relative to the `devcontainer.json` file. | | `build.context` | string | Path that the Docker build should be run from relative to `devcontainer.json`. For example, a value of `".."` would allow you to reference content in sibling directories. Defaults to `"."`. | | `build.args` | Object | A set of name-value pairs containing [Docker image build arguments](https://docs.docker.com/engine/reference/commandline/build/#build-arg) that should be passed when building a Dockerfile. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. Defaults to not set. For example: `"build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }` | +| `build.options` | array | An array of [Docker image build options](https://docs.docker.com/engine/reference/commandline/build/#options) that should be passed to the build command when building a Dockerfile. Defaults to `[]`. For example: `"build": { "options": [ "--add-host=host.docker.internal:host-gateway" ] }` | | `build.target` | string | A string that specifies a [Docker image build target](https://docs.docker.com/engine/reference/commandline/build/#target) that should be passed when building a Dockerfile. Defaults to not set. For example: `"build": { "target": "development" }` | | `build.cacheFrom` | string,
array | A string or array of strings that specify one or more images to use as caches when building the image. Cached image identifiers are passed to the `docker build` command with `--cache-from`. | -| `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-properties). This property accepts a port or array of ports that should be published locally when the container is running.Unlike `forwardPorts`, your application may need to listen on all interfaces (`0.0.0.0`) not just `localhost` for it to be available externally. Defaults to `[]`.
Learn more about publishing vs forwarding ports [here](#publishing-vs-forwarding-ports).
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | +| `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-properties). This property accepts a port or array of ports that should be published locally when the container is running. Unlike `forwardPorts`, your application may need to listen on all interfaces (`0.0.0.0`) not just `localhost` for it to be available externally. Defaults to `[]`.
Learn more about publishing vs forwarding ports [here](#publishing-vs-forwarding-ports).
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | | `workspaceMount` | string | Requires `workspaceFolder` be set as well. Overrides the default local mount point for the workspace when the container is created. Supports the same values as the [Docker CLI `--mount` flag](https://docs.docker.com/engine/reference/commandline/run/#mount). Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the value. For example:
`"workspaceMount": "source=${localWorkspaceFolder}/sub-folder,target=/workspace,type=bind,consistency=cached", "workspaceFolder": "/workspace"` | | `workspaceFolder` | string | Requires `workspaceMount` be set. Sets the default path that `devcontainer.json` supporting services / tools should open when connecting to the container. Defaults to the automatic source code mount location. | | `runArgs` | array | An array of [Docker CLI arguments](https://docs.docker.com/engine/reference/commandline/run/) that should be used when running the container. Defaults to `[]`. For example, this allows ptrace based debuggers like C++ to work in the container:
`"runArgs": [ "--cap-add=SYS_PTRACE", "--security-opt", "seccomp=unconfined" ]` . | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} ### Docker Compose specific properties | Property | Type | Description | |:------------------|:------------|:------------| | `dockerComposeFile` | string,
array | **Required** when using [Docker Compose](https://docs.docker.com/compose/). Path or an ordered list of paths to Docker Compose files relative to the `devcontainer.json` file. Using an array is useful [when extending your Docker Compose configuration](https://docs.docker.com/compose/extends/#multiple-compose-files). The order of the array matters since the contents of later files can override values set in previous ones.
The default `.env` file is picked up from the root of the project, but you can use `env_file` in your Docker Compose file to specify an alternate location.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | -| `service` | string | **Required** when using [Docker Compose](https://docs.docker.com/compose/). The name of the service `devcontainer.json` supporting services / tools should connect to once running. | +| `service` | string | **Required** when using [Docker Compose](https://docs.docker.com/compose/). The name of the service `devcontainer.json` supporting services / tools should connect to once running. | | `runServices` | array | An array of services in your Docker Compose configuration that should be started by `devcontainer.json` supporting services / tools. These will also be stopped when you disconnect unless `"shutdownAction"` is `"none"`. Defaults to all services. | | `workspaceFolder` | string | Sets the default path that `devcontainer.json` supporting services / tools should open when connecting to the container (which is often the path to a volume mount where the source code can be found in the container). Defaults to `"/"`. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} ## Tool-specific properties @@ -76,14 +77,14 @@ When creating or working with a dev container, you may need different commands t | Property | Type | Description | |:------------------|:------------|:------------| -| `initializeCommand` | string,
array,
object | A command string or list of command arguments to run on the **host machine** before the container is created.
⚠️ The command is run wherever the source code is located on the host. For cloud services, this is in the cloud.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | +| `initializeCommand` | string,
array,
object | A command string or list of command arguments to run on the **host machine** during initialization, including during container creation and on subsequent starts. The command may run more than once during a given session.
⚠️ The command is run wherever the source code is located on the host. For cloud services, this is in the cloud.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `onCreateCommand` 🏷️ | string,
array,
object | This command is the first of three (along with `updateContentCommand` and `postCreateCommand`) that finalizes container setup when a dev container is created. It and subsequent commands execute **inside** the container immediately after it has started for the first time.
Cloud services can use this command when caching or prebuilding a container. This means that it will not typically have access to user-scoped assets or secrets.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `updateContentCommand` 🏷️ | string,
array,
object | This command is the second of three that finalizes container setup when a dev container is created. It executes inside the container after `onCreateCommand` whenever new content is available in the source tree during the creation process.
It will execute at least once, but cloud services will also periodically execute the command to refresh cached or prebuilt containers. Like cloud services using `onCreateCommand`, it can only take advantage of repository and org scoped secrets or permissions.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `postCreateCommand` 🏷️ | string,
array,
object | This command is the last of three that finalizes container setup when a dev container is created. It happens after `updateContentCommand` and once the dev container has been assigned to a user for the first time.
Cloud services can use this command to take advantage of user specific secrets and permissions.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `postStartCommand` 🏷️ | string,
array,
object | A command to run each time the container is successfully started.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `postAttachCommand` 🏷️ | string,
array,
object | A command to run each time a tool has successfully attached to the container.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array vs object properties. | | `waitFor` 🏷️ | enum | An enum that specifies the command any tool should wait for before connecting. Defaults to `updateContentCommand`. This allows you to use `onCreateCommand` or `updateContentCommand` for steps that must happen before `devcontainer.json` supporting tools connect while still using `postCreateCommand` for steps that can happen behind the scenes afterwards. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} For each command property, if the value is a single string, it will be run in `/bin/sh`. Use `&&` in a string to execute multiple commands. For example, `"yarn install"` or `"apt-get update && apt-get install -y curl"`. The array syntax `["yarn", "install"]` will invoke the command (in this case `yarn`) directly without using a shell. Each fires after your source code has been mounted, so you can also run shell scripts from your source tree. For example: `bash scripts/install-dev-tools.sh`. @@ -91,16 +92,15 @@ If one of the lifecycle scripts fails, any subsequent scripts will not be execut ## Minimum host requirements -While `devcontainer.json` does not focus on hardware or VM provisioning, it can be useful to know your container's minimum RAM, CPU, storage, and GPU requirements. This is what the `hostRequirements` properties allow you to do. Cloud services can use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. +While `devcontainer.json` does not focus on hardware or VM provisioning, it can be useful to know your container's minimum RAM, CPU, and storage requirements. This is what the `hostRequirements` properties allow you to do. Cloud services can use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. | Property | Type | Description | |:------------------|:------------|:------------| | `hostRequirements.cpus` 🏷️ | integer | Indicates the minimum required number of CPUs / virtual CPUs / cores. For example: `"hostRequirements": {"cpus": 2}` | | `hostRequirements.memory` 🏷️ | string | A string indicating minimum memory requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"memory": "4gb"}` | | `hostRequirements.storage` 🏷️ | string | A string indicating minimum storage requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"storage": "32gb"}` | -| `hostRequirements.gpu` 🏷️ | boolean, string or object | Indicates whether a GPU is required. The string \"optional\" indicates that a GPU is optional. An object value can be used to configure more detailed requirements. For example: `"hostRequirements": {"gpu": true}` | - -{: .table .table-bordered .table-responsive} +| `hostRequirements.gpu` 🏷️ | boolean,
string,
object | Indicates if any GPU is required. A boolean indicates if a GPU is required or not. The string `"optional"` indicates that a GPU is used when available, but is not required.
The object syntax specifies how much GPU resources are required. The `cores` property indicates the minimum number of cores and the `memory` property indicates minimum storage requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"gpu": { "cores": 1000, "storage": "32gb" }` | + {: .table .table-bordered} ## Port attributes @@ -110,10 +110,10 @@ The `portsAttributes` and `otherPortsAttributes` properties allow you to map def |:------------------|:------------|:------------| | `label` 🏷️ | string | Display name for the port in the ports view. Defaults to not set. | | `protocol` 🏷️ | enum | Controls protocol handling for forwarded ports. When not set, the port is assumed to be a raw TCP stream which, if forwarded to `localhost`, supports any number of protocols. However, if the port is forwarded to a web URL (e.g. from a cloud service on the web), only HTTP ports in the container are supported. Setting this property to `https` alters handling by ignoring any SSL/TLS certificates present when communicating on the port and using the correct certificate for the forwarded URL instead (e.g `https://*.githubpreview.dev`). If set to `http`, processing is the same as if the protocol is not set. Defaults to not set. | -| `onAutoForward` 🏷️ | enum | Controls what should happen when a port is auto-forwarded once you've connected to the container. `notify` is the default, and a notification will appear when the port is auto-forwarded. If set to `openBrowser`, the port will be opened in the system's default browser. `openPreview` will open the URL in `devcontainer.json` supporting services' / tools' embedded preview browser. A value of `openBrowserOnce` will only open the browser once. A value of `silent` will forward the port, but take no further action. A value of `ignore` means that this port should not be auto-forwarded at all. | +| `onAutoForward` 🏷️ | enum | Controls what should happen when a port is auto-forwarded once you've connected to the container. `notify` is the default, and a notification will appear when the port is auto-forwarded. If set to `openBrowser`, the port will be opened in the system's default browser. A value of `openBrowserOnce` will open the browser only once. `openPreview` will open the URL in `devcontainer.json` supporting services' / tools' embedded preview browser. A value of `silent` will forward the port, but take no further action. A value of `ignore` means that this port should not be auto-forwarded at all. | | `requireLocalPort` 🏷️ | boolean | Dictates when port forwarding is required to map the port in the container to the same port locally or not. If set to `false`, the `devcontainer.json` supporting services / tools will attempt to use the specified port forward to `localhost`, and silently map to a different one if it is unavailable. If set to `true`, you will be notified if it is not possible to use the same port. Defaults to `false`. | | `elevateIfNeeded` 🏷️ | boolean | Forwarding low ports like 22, 80, or 443 to `localhost` on the same port from `devcontainer.json` supporting services / tools may require elevated permissions on certain operating systems. Setting this property to `true` will automatically try to elevate the `devcontainer.json` supporting tool's permissions in this situation. Defaults to `false`. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} ## Formatting string vs. array properties @@ -163,16 +163,16 @@ Finally, you may use an object format: Variables can be referenced in certain string values in `devcontainer.json` in the following format: **${variableName}**. The following is a list of available variables you can use. -| Property | Type | Description | +| Variable | Properties | Description | |:------------------|:------------|:------------| -| `${localEnv:VARIABLE_NAME}` | Any | Value of an environment variable on the **host machine** (in this case, called `VARIABLE_NAME`). Unset variables are left blank. For example, this would set a variable to your local home folder on Linux / macOS or the user folder on Windows:
`"remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" }`
A default value for when the environment variable is not set can be given with `${localEnv:VARIABLE_NAME:default_value}`.
⚠️ For a cloud service, the host is in the cloud rather than your local machine. | +| `${localEnv:VARIABLE_NAME}` | Any | Value of an environment variable on the **host machine** (in the examples below, called `VARIABLE_NAME`). Unset variables are left blank.
⚠️ Clients (like VS Code) may need to be **restarted** to pick up newly set variables.
⚠️ For a cloud service, the host is in the cloud rather than your local machine.
**Examples**
**1.** Set a variable containing your local home folder on Linux / macOS or the user folder on Windows:
`"remoteEnv": { "LOCAL_USER_PATH": "${localEnv:HOME}${localEnv:USERPROFILE}" }`.
A default value for when the environment variable is not set can be given with `${localEnv:VARIABLE_NAME:default_value}`.
**2.** In modern versions of macOS, default configurations allow setting local variables with the command `echo 'export VARIABLE_NAME=my-value' >> ~/.zshenv`. | | `${containerEnv:VARIABLE_NAME}` | `remoteEnv` | Value of an existing environment variable inside the container once it is up and running (in this case, called `VARIABLE_NAME`). For example:
`"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }`
A default value for when the environment variable is not set can be given with `${containerEnv:VARIABLE_NAME:default_value}`. | | `${localWorkspaceFolder}` | Any | Path of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`). | | `${containerWorkspaceFolder}` | Any | The path that the workspaces files can be found in the container. | | `${localWorkspaceFolderBasename}` | Any | Name of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`). | | `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | -| `${devcontainerId}` | Any | Identifier derived from a set of container labels that uniquely identify the dev container on a Docker host. It allows Features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.
The properties supporting it in devcontainer.json are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, and `customizations`. | -{: .table .table-bordered .table-responsive} +| `${devcontainerId}` | Any | Allow Features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.
The properties supporting it in devcontainer.json are: `name`, `runArgs`, `initializeCommand`, `onCreateCommand`, `updateContentCommand`, `postCreateCommand`, `postStartCommand`, `postAttachCommand`, `workspaceFolder`, `workspaceMount`, `mounts`, `containerEnv`, `remoteEnv`, `containerUser`, `remoteUser`, and `customizations`. | +{: .table .table-bordered} ## Schema diff --git a/_implementors/json_schema.md b/_implementors/json_schema.md index 1b2d5ff8..6f733bfc 100644 --- a/_implementors/json_schema.md +++ b/_implementors/json_schema.md @@ -205,7 +205,8 @@ You may review the current devcontainer.json schemas in the spec repo, which inc "string", "array" ], - "description": "A command to run locally before anything else. This command is run before \"onCreateCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell.", + "description": "A command string or list of command arguments to run on the host machine during initialization, including during container creation and on subsequent starts. The command may run more than once during a given session. This command is run before \"onCreateCommand\". If this is a single string, it will be run in a shell. If this is an array of strings, it will be run as a single command without shell.", + "items": { "type": "string" } diff --git a/_implementors/reference.md b/_implementors/reference.md index 3c43c914..6d75dd56 100644 --- a/_implementors/reference.md +++ b/_implementors/reference.md @@ -6,18 +6,18 @@ author: Microsoft index: 2 --- -The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a devcontainer.json and create and configure a dev container from it. +The reference implementation for the specification is available through a [development container CLI](https://github.com/devcontainers/cli). This CLI can take a `devcontainer.json` and create and configure a dev container from it. -## What is the dev container CLI? -When tools like VS Code and Codespaces detect a devcontainer.json file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in devcontainer.json metadata and create dev containers from it. +## What is the Dev Container CLI? +When tools like VS Code and Codespaces detect a `devcontainer.json` file in a user's project, they use a CLI to configure a dev container. We've now opened up this CLI as a reference implementation so that individual users and other tools can read in `devcontainer.json` metadata and create dev containers from it. This CLI can either be used directly or integrated into product experiences, similar to how it's integrated with Dev Containers and Codespaces today. It currently supports both a simple single container option and integrates with [Docker Compose](https://docs.docker.com/compose/) for multi-container scenarios. -The CLI is available for review in a new [devcontainers/cli](https://github.com/devcontainers/cli) repository, and you can read more about its development in [this issue](https://github.com/devcontainers/spec/issues/9) in the spec repo. +The CLI is available in the [devcontainers/cli](https://github.com/devcontainers/cli) repository. ## How can I try it? -We'd love for you to try out the dev container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources. +We'd love for you to try out the Dev Container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources. You may learn more about building from sources in the [CLI repo's README](https://github.com/devcontainers/cli#try-it-out). On this page, we'll focus on using the npm package. @@ -97,7 +97,7 @@ Hello, VS Code Remote - Containers! {"outcome":"success"} ``` -Congrats, you've just run the dev container CLI and seen it in action! +Congrats, you've just run the Dev Container CLI and seen it in action! These steps are also provided in the CLI repo's [README](https://github.com/devcontainers/cli/blob/main/README.md). You may also review frequently asked questions [here](https://github.com/devcontainers/spec/issues/31). @@ -110,13 +110,15 @@ We recommend using the [Dev Container CLI](#npm-install) (or other spec supporti devcontainer build --workspace-folder . --push true --image-name
+ 
+
+
+An example diff generated by Dependabot is shown below:
+
+```diff
+---
+ .devcontainer-lock.json | 8 ++++----
+ .devcontainer.json | 2 +-
+ 2 files changed, 5 insertions(+), 5 deletions(-)
+
+diff --git a/.devcontainer-lock.json b/.devcontainer-lock.json
+index 324582b..a3868d9 100644
+--- a/.devcontainer-lock.json
++++ b/.devcontainer-lock.json
+@@ -1,9 +1,9 @@
+ {
+ "features": {
+- "ghcr.io/devcontainers/features/docker-in-docker:1": {
+- "version": "1.0.9",
+- "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:b4c04ba88371a8ec01486356cce10eb9fe8274627d8d170aaec87ed0d333080d",
+- "integrity": "sha256:b4c04ba88371a8ec01486356cce10eb9fe8274627d8d170aaec87ed0d333080d"
++ "ghcr.io/devcontainers/features/docker-in-docker:2": {
++ "version": "2.7.1",
++ "resolved": "ghcr.io/devcontainers/features/docker-in-docker@sha256:f6a73ee06601d703db7d95d03e415cab229e78df92bb5002e8559bcfc047fec6",
++ "integrity": "sha256:f6a73ee06601d703db7d95d03e415cab229e78df92bb5002e8559bcfc047fec6"
+ }
+ }
+ }
+\ No newline at end of file
+diff --git a/.devcontainer.json b/.devcontainer.json
+index e9d9af5..9eb9165 100644
+--- a/.devcontainer.json
++++ b/.devcontainer.json
+@@ -1,6 +1,6 @@
+ {
+ "image": "mcr.microsoft.com/devcontainers/base:jammy",
+ "features": {
+- "ghcr.io/devcontainers/features/docker-in-docker:1": {}
++ "ghcr.io/devcontainers/features/docker-in-docker:2": {}
+ }
+ }
+```
+
+ This updater ensures publicly-accessible Features are pinned to the latest version in the associated `devcontainer.json` file. If a dev container has an associated lockfile, that file will also be updated. For more information on lockfiles, see this [specification](https://github.com/devcontainers/spec/blob/main/docs/specs/devcontainer-lockfile.md).
+
+Features in any [valid dev container location](https://containers.dev/implementors/spec/#devcontainerjson) will be updated in a single pull request.
+
+Dependabot version updates are free to use for all repositories on GitHub.com. For more information [see the Dependabot version update documentation](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/about-dependabot-version-updates#supported-repositories-and-ecosystem).
diff --git a/collections.html b/collections.html
index 205688e5..2dc28bf0 100644
--- a/collections.html
+++ b/collections.html
@@ -6,24 +6,60 @@
+Collections
- This list below contains pointers to official and community-contributed Dev Container assets, including Features and Templates. - Collections on this list are continuously crawled for liveness, and can be presented in UX of Dev Container-supporting tools + This list below contains pointers to official and community-contributed dev container assets, including Features and + Templates. + Collections on this list are continuously crawled for liveness, and can be presented in UX of spec supporting tools (i.e. it will be presented in the GitHub Codespaces and VS Code Dev Containers UX).
- To add your own collection to this list, please create a PR editing this yaml file. + To add your own collection to this list, please create a PR editing this + yaml file.
-+
+ +
| Name | +Maintainer | +Repository | +
| {{ c.name }} | +{{ c.maintainer | strip_html }} + | +{{ c.repository | strip_html + }} + | +
Available Dev Container Features
This table contains all official and community-supported Dev Container Features
- known at the time of crawling each registered collection. This list is continuously
- updated with the latest available feature information. See the
- Feature quick start repository to add your own!
+ known at the time of crawling each registered collection. This list is continuously
+ updated with the latest available feature information. See the
+ Feature quick start repository to add your own!
- Referencing a feature below can be done in the "features" section of a devcontainer.json.
+ Referencing a Feature below can be done in the "features"
+ section of a devcontainer.json.
Please note that if you need to report a Feature, you should do so through the registry hosting the Feature.
+ To add your own collection to this list, please create a PR editing this + yaml file.
-+
+ +
| Feature Name | +Maintainer | +Reference | +Latest Version | +
| {{ f.name | strip_html }} | -{{ c.sourceInformation.maintainer | strip_html }} | -{{ f.id | strip_html }}:{{ f.majorVersion | strip_html }} |
- {{ f.version | strip_html }} |
-
| {{ f.name | strip_html }} + | +{{ c.sourceInformation.maintainer | strip_html }} | +{{ f.id | strip_html }}:{{ f.majorVersion | strip_html }} |
+ {{ f.version | strip_html }} |
+
Development Containers
- Star
@@ -27,44 +28,61 @@ Development Containers
- 
-
+
- Use or create dev container definitions for a multitude of tech stacks and tools.
+
+ Use or create dev container definitions for a multitude of tech stacks and + tools.
+
-
-
-
+
\ No newline at end of file
diff --git a/overview.md b/overview.md
index ccfb5e1f..6858efa8 100644
--- a/overview.md
+++ b/overview.md
@@ -7,17 +7,17 @@ sectionid: overview
## What are development containers?
As containerizing production workloads becomes commonplace, more developers are using containers for scenarios beyond deployment, including continuous integration, test automation, and even full-featured coding environments.
-Each scenario’s needs can vary between simple single container environments to complex, orchestrated multi-container setups. Rather than attempting to create another orchestrator format, the Development Containers Specification (or Dev Containers Spec for short) seeks to find ways to enrich existing formats with metadata for common development specific settings, tools, and configuration.
+Each scenario’s needs can vary between simple single container environments to complex, orchestrated multi-container setups. Rather than attempting to create another orchestrator format, the Development Container Specification (or Dev Container Spec for short) seeks to find ways to enrich existing formats with metadata for common development specific settings, tools, and configuration.
### A structured metadata format
Like the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) before it, the first format in the specification, [`devcontainer.json`](implementors/json_reference), was born out of necessity. It is a structured JSON with Comments (jsonc) metadata format that tools can use to store any needed configuration required to develop inside of local or cloud-based containerized coding.
-Since the spec was initally published, Dev Container metadata can now be stored in [image labels](../implementors/spec/#image-metadata) and in reusable chunks of metadata and install scripts known as [Dev Container Features](../features). We envision that this same structured data can be embedded in other formats -- all while retaining a common object model for consistent processing.
+Since the spec was initally published, dev container metadata can now be stored in [image labels](../implementors/spec/#image-metadata) and in reusable chunks of metadata and install scripts known as [Dev Container Features](../features). We envision that this same structured data can be embedded in other formats -- all while retaining a common object model for consistent processing.
### Development vs production
-A Development Container defines an environment in which you develop your application before you are ready to deploy. While deployment and development containers may resemble one another, you may not want to include tools in a deployment image that you use during development.
+A development container defines an environment in which you develop your application before you are ready to deploy. While deployment and development containers may resemble one another, you may not want to include tools in a deployment image that you use during development.
-
- {% assign sorted = site.implementors | sort: 'index' %}
-
- 
Specification
-- Check out the latest reference implementation and schemas. -
-
-
-
-
Supporting Tools
-- A variety of tools and services support this standard. -
+
+
+
-
+
+ {% assign sorted = site.implementors | sort: 'index' %}
+
+
+
Specification
+ ++ Check out the latest reference implementation and schemas. +
+
diff --git a/supporting.md b/supporting.md
index 3569f680..e1e37d1a 100644
--- a/supporting.md
+++ b/supporting.md
@@ -4,7 +4,7 @@ layout: singlePage
sectionid: supporting
---
-This page outlines tools and services that currently support the development container specification, including the `devcontainer.json` format. A `devcontainer.json` file in your project tells tools and services that support the dev container spec how to access (or create) a dev container with a well-defined tool and runtime stack.
+This page outlines tools and services that currently support the Development Container Specification, including the `devcontainer.json` format. A `devcontainer.json` file in your project tells tools and services that support the dev container spec how to access (or create) a dev container with a well-defined tool and runtime stack.
While most [dev container properties](implementors/json_reference) apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools, which are outlined below.
@@ -29,19 +29,19 @@ Visual Studio Code specific properties go under `vscode` inside `customizations`
|:------------------|:------------|:------------|
| `extensions` | array | An array of extension IDs that specify the extensions that should be installed inside the container when it is created. Defaults to `[]`. |
| `settings` | object | Adds default `settings.json` values into a container/machine specific settings file. Defaults to `{}`. |
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
Please note that the [Dev Containers](#dev-containers) extension and [GitHub Codespaces](#github-codespaces) support these VS Code properties.
### Visual Studio
-Visual Studio added Dev Container support in Visual Studio 2022 17.4 for C++ projects using CMake Presets. It is part of the Linux and embedded development with C++ workload, so make sure it is selected in your VS installation. Visual Studio manages the lifecycle of Dev Containers it uses as you work, but it treats them as remote targets in a similar way to other Linux or WSL targets.
+Visual Studio added dev container support in Visual Studio 2022 17.4 for C++ projects using CMake Presets. It is part of the Linux and embedded development with C++ workload, so make sure it is selected in your VS installation. Visual Studio manages the lifecycle of dev containers it uses as you work, but it treats them as remote targets in a similar way to other Linux or WSL targets.
You may learn more in the [announcement blog post](https://devblogs.microsoft.com/cppblog/dev-containers-for-c-in-visual-studio/).
### IntelliJ IDEA
-IntelliJ IDEA has early support Dev Containers that can be run remotely via an SSH connection or locally using Docker.
+IntelliJ IDEA has early support dev containers that can be run remotely via an SSH connection or locally using Docker.
You may learn more in the [announcement blog post](https://blog.jetbrains.com/idea/2023/06/intellij-idea-2023-2-eap-6/#SupportforDevContainers).
@@ -49,25 +49,25 @@ You may learn more in the [announcement blog post](https://blog.jetbrains.com/id
### Dev Container CLI
-The dev container command line interface (CLI) is a reference implementation for the Dev Container spec. It is in development in the [devcontainers/cli](https://github.com/devcontainers/cli) repo. It is intended both for use directly and by tools or services that want to support the spec.
+The Dev Container Command Line Interface (CLI) is a reference implementation for the Dev Container Spec. It is in development in the [devcontainers/cli](https://github.com/devcontainers/cli) repo. It is intended both for use directly and by tools or services that want to support the spec.
-The CLI can take a `devcontainer.json` and create and configure a dev container from it. It allows for prebuilding dev container definitions using a CI or DevOps product like GitHub Actions. It can detect and include dev container features and apply them at container runtime, and run [lifecycle scripts](implementors/json_reference/#lifecycle-scripts) like `postCreateCommand`, providing more power than a plain `docker build` and `docker run`.
+The CLI can take a `devcontainer.json` and create and configure a dev container from it. It allows for prebuilding dev container configurations using a CI or DevOps product like GitHub Actions. It can detect and include dev container features and apply them at container runtime, and run [lifecycle scripts](implementors/json_reference/#lifecycle-scripts) like `postCreateCommand`, providing more power than a plain `docker build` and `docker run`.
#### VS Code extension CLI
-The [VS Code Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) includes a variation of the devcontainer CLI that adds the ability use the command line to open a dev container in VS Code. It is also automatically updated when the extension updates.
+The [VS Code Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) includes a variation of the Dev Container CLI that adds the ability use the command line to open a dev container in VS Code. It is also automatically updated when the extension updates.
Press cmd/ctrl+shift+p or F1 and select the **Dev Containers: Install devcontainer CLI** command to install it.
### Cachix devenv
-Cachix's **[devenv](https://devenv.sh/)** now supports automatically generating a `.devcontainer.json` file. This gives you a more convenient and consistent way to use [Nix](https://nixos.org/) with any Dev Container spec supporting tool or service!
+Cachix's **[devenv](https://devenv.sh/)** now supports automatically generating a `.devcontainer.json` file. This gives you a more convenient and consistent way to use [Nix](https://nixos.org/) with any Dev Container Spec supporting tool or service!
See [devenv documentation](https://devenv.sh/integrations/codespaces-devcontainer/) for detais.
-### Jetpack.io Devbox
+### Jetify Devbox
-[Jetpack.io](https://jetpack.io) is a [Nix](https://nixos.org/)-based service for deploying applications. [DevBox](https://www.jetpack.io/devbox/) provides a way to use Nix to generate a development environment. [Jetpack.io's VS Code extension](https://marketplace.visualstudio.com/items?itemName=jetpack-io.devbox) allows you to quickly take advantage of DevBox in any Dev Container spec supporting tool or service.
+[Jetify](https://jetify.com) (formerly jetpack.io) is a [Nix](https://nixos.org/)-based service for deploying applications. [DevBox](https://www.jetify.com/devbox/) provides a way to use Nix to generate a development environment. [Jetify's VS Code extension](https://marketplace.visualstudio.com/items?itemName=jetpack-io.devbox) allows you to quickly take advantage of DevBox in any Dev Container Spec supporting tool or service.
Press cmd/ctrl+shift+p or F1 and select the **Generate Dev Container files** command to get started!
@@ -91,7 +91,7 @@ Some properties may also have certain limitations in the Dev Containers extensio
| `workspaceFolder` | string | Not yet supported when using Clone Repository in Container Volume. |
| `${localWorkspaceFolder}` | Any | Not yet supported when using Clone Repository in Container Volume. |
| `${localWorkspaceFolderBasename}` | Any | Not yet supported when using Clone Repository in Container Volume. |
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
## Services
@@ -136,11 +136,11 @@ You can customize which files are initially opened when the codespace is created
The paths are relative to the root of the repository. They will be opened in order, with the first file activated.
-Note that currently Codespaces reads these properties from devcontainer.json, not image metadata.
+> **Note** that currently Codespaces reads these properties from `devcontainer.json`, not image metadata.
#### Product specific limitations
-Some properties may apply differently to Codespaces.
+Some properties may apply differently to codespaces.
| Property or variable | Type | Description |
|----------|---------|----------------------|
@@ -151,7 +151,7 @@ Some properties may apply differently to Codespaces.
| `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.|
| `customizations.codespaces` | object | Codespaces reads this property from devcontainer.json, not image metadata. |
| `hostRequirements` | object | Codespaces reads this property from devcontainer.json, not image metadata. |
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
### CodeSandbox
@@ -159,7 +159,6 @@ Some properties may apply differently to Codespaces.
When you import a GitHub repository into CodeSandbox, it will automatically provision a dedicated environment for every branch. Thanks to memory snapshotting, CodeSandbox then resumes and branches an environment in under two seconds.
-
CodeSandbox offers support for multiple editors, so you can code using the CodeSandbox web editor, VS Code, or the CodeSandbox iOS app.
**Tip:** After importing a repository into CodeSandbox, you can use the built-in UI to configure the environment using dev containers.
@@ -171,32 +170,38 @@ All properties specific to CodeSandbox are placed within a `.codesandbox` folder
More details about these can be found in the CodeSandbox [documentation](https://codesandbox.io/docs/learn/repositories/task).
-#### Product specific limitations
+#### Product specific limitations
CodeSandbox runs dev containers using rootless Podman instead of Docker. CodeSandbox also uses [devcontainers/cli](https://github.com/devcontainers/cli) to manage dev containers. So any limitations of rootless Podman and Dev Container CLI should apply to CodeSandbox.
-
The following properties apply differently to CodeSandbox.
| Property or variable | Type | Description |
|----------|---------|----------------------|
| `forwardPorts` | array | CodeSandbox does not need this property. All ports opened in dev containers will be mapped to a public URL automatically. |
-
| `portsAttributes` | object | CodeSandbox does not yet support this property. Ports are attached to tasks configured in `.codesandbox/tasks.json` and are attributed to the tasks.|
| `otherPortsAttributes` | object | CodeSandbox does not yet support this property. |
| `remoteUser` | string | CodeSandbox currently ignores this property and overrides this as `root`. CodeSandbox uses rootless Podman to run containers. Running with a non-root remote user is the same as running as a root remote user in rootless Podman, from a security perspective. CodeSandbox plans on supporting this in the future. |
| `shutdownAction` | string | Does not apply to CodeSandbox. |
-
| `capAdd` | array | CodeSandbox does not support adding docker capabilities. As the containers are run as a non-root user, capabilities that need root access will not work. |
-
| `features` | object | CodeSandbox automatically adds docker-cli to the container and connects to the host socket. Features like `docker-in-docker` and `docker-outside-of-docker` will work a bit differently. As the docker-cli and socket from host are accessible in the container, most use cases should work as expected. |
| `${localEnv:VARIABLE_NAME}` | Any | For CodeSandbox, the host is in the cloud rather than in your local machine.|
| `hostRequirements` | object | CodeSandbox does not yet support this property. |
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
### DevPod
-[DevPod](https://github.com/loft-sh/devpod) is a client-only tool to create reproducible developer environments based on a devcontainer.json on any backend. Each developer environment runs in a container and is specified through a devcontainer.json. Through DevPod providers these environments can be created on any backend, such as the local computer, a Kubernetes cluster, any reachable remote machine or in a VM in the cloud.
+[DevPod](https://github.com/loft-sh/devpod) is a client-only tool to create reproducible developer environments based on a `devcontainer.json` on any backend. Each developer environment runs in a container and is specified through a `devcontainer.json`. Through DevPod providers these environments can be created on any backend, such as the local computer, a Kubernetes cluster, any reachable remote machine or in a VM in the cloud.
+
+### Gitpod
+
+[**Gitpod Flex**](https://www.gitpod.io/) is a platform for automating and standardizing development environments. Available as a self-hosted solution in your cloud or for local development through Gitpod Desktop, Gitpod Flex scales to support environments with up to 896 vCPUs and 12TB of RAM, including GPU support and compatibility with multiple editors like VS Code, JetBrains, Cursor, and Zed.
+
+Gitpod Flex fully adheres to the Dev Container Specification, enabling developers to create portable and reproducible environments through `devcontainer.json`. To apply changes, simply run `gitpod environment devcontainer rebuild` from within any development environment.
+
+
+For more details on constraints, customizations, and automation options, please refer to the [blog announcement](https://www.gitpod.io/blog/gitpod-supports-development-container).
+
### Schema
diff --git a/templates.html b/templates.html
index 089fe51c..a33d1702 100644
--- a/templates.html
+++ b/templates.html
@@ -17,18 +17,54 @@ Available Dev Container Templa
+ To add your own collection to this list, please create a PR editing this + yaml file.
-+
+ +
| Template Name | +Maintainer | +Reference | +Latest Version | +||
| {{ f.name | strip_html }} | -{{ c.sourceInformation.maintainer | strip_html }} | +{{ f.name | strip_html }} + | +{{ c.sourceInformation.maintainer | strip_html }} | +{{ f.id | strip_html }}:{{ f.version | strip_html }} |
+ {{ f.version | strip_html }} |