`"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]` | -{: .table .table-bordered .table-responsive} +| `mounts` | object | Defaults to unset. Cross-orchestrator way to add additional mounts to a container. Each value is an object that accepts the same values as the [Docker CLI `--mount` flag](https://docs.docker.com/engine/reference/commandline/run/#mount). The Pre-defined [devcontainerId](/implementors/json_reference#variables-in-devcontainerjson) variable may be referenced in the value. For example:
`"mounts": [{ "source": "dind-var-lib-docker", "target": "/var/lib/docker", "type": "volume" }]` | +{: .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/#add-bind-mounts-or-volumes-using-the---mount-flag). 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" }]` | +| `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 @@ -47,24 +47,25 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `image` | string | **Required** when using an image. The name of an image in a container registry ([DockerHub](https://hub.docker.com), [GitHub Container Registry](https://docs.github.com/packages/guides/about-github-container-registry), [Azure Container Registry](https://azure.microsoft.com/services/container-registry/)) that `devcontainer.json` supporting services / tools should use to create the dev container. | | `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/#set-build-time-variables---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.target` | string | A string that specifies a [Docker image build target](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) that should be passed when building a Dockerfile. Defaults to not set. For example: `"build": { "target": "development" }` | +| `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. | -| `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/#add-bind-mounts-or-volumes-using-the---mount-flag). 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"` | +| `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`. @@ -98,7 +99,8 @@ While `devcontainer.json` does not focus on hardware or VM provisioning, it can | `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"}` | -{: .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 @@ -108,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 @@ -161,20 +163,20 @@ 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 -You can see the VS Code implementation of the dev container schema [here](https://github.com/microsoft/vscode/blob/main/extensions/configuration-editing/schemas/devContainer.schema.src.json). +You can see the dev container schema [here](https://github.com/devcontainers/spec/blob/main/schemas/devContainer.base.schema.json). ## Publishing vs forwarding ports diff --git a/_implementors/json_schema.md b/_implementors/json_schema.md index 05b2ce65..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" } @@ -352,6 +353,39 @@ You may review the current devcontainer.json schemas in the spec repo, which inc "type": "string", "pattern": "^\\d+([tgmk]b)?$", "description": "Amount of required disk space in bytes. Supports units tb, gb, mb and kb." + }, + "gpu": { + "oneOf": [ + { + "type": [ + "boolean", + "string" + ], + "enum": [ + true, + false, + "optional" + ], + "description": "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." + }, + { + "type": "object", + "properties": { + "cores": { + "type": "integer", + "minimum": 1, + "description": "Number of required cores." + }, + "memory": { + "type": "string", + "pattern": "^\\d+([tgmk]b)?$", + "description": "Amount of required RAM in bytes. Supports units tb, gb, mb and kb." + } + }, + "description": "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.", + "additionalProperties": false + } + ] } } } diff --git a/_implementors/reference.md b/_implementors/reference.md index 9442ca36..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
- © 2022 Microsoft
+ © {{ 'now' | date: "%Y" }} Microsoft
diff --git a/_layouts/post.html b/_layouts/post.html
index 3bf16631..06a0a3dd 100644
--- a/_layouts/post.html
+++ b/_layouts/post.html
@@ -2,7 +2,13 @@
layout: singlePage
---
-
\ No newline at end of file
+
diff --git a/_posts/2022-11-01-author-a-feature.md b/_posts/2022-11-01-author-a-feature.md
index ed9f3a7d..ab7a0139 100644
--- a/_posts/2022-11-01-author-a-feature.md
+++ b/_posts/2022-11-01-author-a-feature.md
@@ -1,15 +1,17 @@
---
layout: post
title: "Authoring a Dev Container Feature"
-author: "@joshspicer"
-authorUrl: https://github.com/joshspicer
+author:
+ - "@joshspicer"
+authorUrl:
+ - https://github.com/joshspicer
---
Development container ["Features"](/features) are self-contained, shareable units of installation code and development container configuration. We [define a pattern](/implementors/features-distribution) for authoring and self-publishing Features.
In this document, we'll outline a "quickstart" to help you get up-and-running with creating and sharing your first Feature. You may review an example along with guidance in our [devcontainers/feature-starter](https://github.com/devcontainers/feature-starter) repo as well.
-> Note: While this walkthrough will illustrate the use of GitHub and the GitHub Container Registry, you can use your own source control system and publish to any [OCI Artifact supporting](https://oras.land/implementors/#registries-supporting-oci-artifacts) container registry instead.
+> Note: While this walkthrough will illustrate the use of GitHub and the GitHub Container Registry, you can use your own source control system and publish to any [OCI Artifact supporting](https://oras.land/docs/compatible_oci_registries#registries-supporting-oci-artifacts) container registry instead.
## Create a repo
diff --git a/_posts/2022-12-16-dockerfile.md b/_posts/2022-12-16-dockerfile.md
index 687f13d5..c0b44d68 100644
--- a/_posts/2022-12-16-dockerfile.md
+++ b/_posts/2022-12-16-dockerfile.md
@@ -1,8 +1,10 @@
---
layout: post
title: "Using Images, Dockerfiles, and Docker Compose"
-author: "@chuxel"
-authorUrl: https://github.com/chuxel
+author:
+ - "@chuxel"
+authorUrl:
+ - https://github.com/chuxel
---
When creating a development container, you have a variety of different ways to customize your environment like ["Features"](/features) or [lifecycle scripts](/implementors/json_reference/#lifecycle-scripts). However, if you are familiar with containers, you may want to use a [Dockerfile](/guide/dockerfile#dockerfile) or [Docker Compose / Compose](/guide/dockerfile#docker-compose) to customize your environment. This article will walk through how to use these formats with the Dev Container spec.
@@ -32,7 +34,7 @@ Next, remove the `image` property from `devcontainer.json` (if it exists) and ad
```json
{
"build": {
- // Path is relataive to the devcontainer.json file.
+ // Path is relative to the devcontainer.json file.
"dockerfile": "Dockerfile"
}
}
@@ -44,7 +46,7 @@ That's it! When you start up your Dev Container, the Dockerfile will be automati
Better yet, you can can use a Dockerfile as a part of authoring an image you can share with others. You can even **add Dev Container settings and metadata right into the image itself**. This avoids having to duplicate config and settings in multiple devcontainer.json files and keeps them in sync with your images!
-See the reference on **[pre-building](/implementors/reference/#prebuilding)** to learn more!
+See the guide on **[pre-building]({% post_url 2023-08-22-prebuild %})** to learn more!
## Using Docker Compose
@@ -138,6 +140,6 @@ volumes:
postgres-data:
```
-Finally, as in the Dockerfile example, you can use this same setup to author a Dev Container image you can share with others and add Dev Container settings and metadata right into the image itself.
+Finally, as in the Dockerfile example, you can use this same setup to create a Dev Container image that you can share with others. You can also add Dev Container settings and metadata right into the image itself.
-See the reference on **[pre-building](/implementors/reference/#prebuilding)** to learn more!
\ No newline at end of file
+See the guide on **[pre-building]({% post_url 2023-08-22-prebuild %})** to learn more!
diff --git a/_posts/2023-02-15-gitlab-ci.md b/_posts/2023-02-15-gitlab-ci.md
index 85104558..63d3b5d0 100644
--- a/_posts/2023-02-15-gitlab-ci.md
+++ b/_posts/2023-02-15-gitlab-ci.md
@@ -1,8 +1,10 @@
---
layout: post
title: "Working with GitLab CI"
-author: "@raginjason"
-authorUrl: https://github.com/raginjason
+author:
+ - "@raginjason"
+authorUrl:
+ - https://github.com/raginjason
---
For simple use cases you can use your development container (dev container) for CI without much issue. Once you begin using more advanced dev container functionality such as [Features](/features), you will need dev container tooling in your CI pipeline. While GitHub CI has the [devcontainers-ci GitHub Action](https://github.com/marketplace/actions/devcontainers-ci), there is no such analog in GitLab CI. To achieve the goal of using your dev container in GitLab CI, the container must be pre-built.
diff --git a/_posts/2023-06-14-feature-authoring-best-practices.md b/_posts/2023-06-14-feature-authoring-best-practices.md
new file mode 100644
index 00000000..adca4d49
--- /dev/null
+++ b/_posts/2023-06-14-feature-authoring-best-practices.md
@@ -0,0 +1,162 @@
+---
+layout: post
+title: "Best Practices: Authoring a Dev Container Feature"
+author:
+ - "@joshspicer"
+authorUrl:
+ - https://github.com/joshspicer
+---
+
+Last November I wrote about the basics around [authoring a Dev Container Feature](/guide/author-a-feature). Since then, [hundreds](https://containers.dev/features) of Features have been written by the community. The flexibility of Features has enabled a wide variety of use cases, from installing a single tool to setting up specific aspects of a project's development environment that can be shared across repositories. To that effect, many different patterns for Feature authorship have emerged, and the core team has learned a lot about what works well and what doesn't.
+
+## Utilize the `test` command
+
+Bundled with the [devcontainer cli](https://github.com/devcontainers/cli) is the `devcontainer features test` command. This command is designed to help Feature authors test their Feature in a variety of scenarios. It is highly recommended that Feature authors use this command to test their Feature before publishing. Some documentation on the `test` command can be found [here](https://github.com/devcontainers/cli/blob/main/docs/features/test.md), and an example can be found in the [Feature quick start repo](https://github.com/devcontainers/feature-starter). This repo is updated periodically as new functionality is added to the reference implementation.
+
+## Feature idempotency
+
+The most useful Features are idempotent. This means that if a Feature is installed multiple times with different options (something that will come into play with [Feature Dependencies](https://github.com/devcontainers/spec/blob/main/proposals/feature-dependencies.md)), the Feature should be able to handle this gracefully. This is especially important for option-rich Features that you anticipate others may depend on in the future.
+
+> 🔧 There is an open spec proposal for installing the same Feature twice in a given `devcontainer.json` [(devcontainers/spec#44)](https://github.com/devcontainers/spec/issues/44). While the syntax to do so in a given `devcontainer.json` is not yet defined, Feature dependencies will effectively allow for this.
+
+For Features that install a versioned tool (eg: version x of `go` and version y of `ruby` ), a robust Feature should be able to install multiple versions of the tool. If your tool has a version manager (java's `SDKMAN`, ruby's `rvm`) it is usually as simple as installing the version manager and then running a command to install the desired version of that tool.
+
+For instances where there isn't an existing version manager available, a well-designed Feature should consider installing distict versions of itself to a well known location. A pattern that many Features utilize successfully is writing each version of each tool to a central folder and symlinking the "active" version to a folder on the PATH.
+
+Features can redefine the PATH variable with `containerEnv`, like so:
+
+```bash
+# devcontainer-feature.json
+"containerEnv": {
+ "PATH": "/usr/local/myTool/bin:${PATH}"
+}
+```
+
+> 🔧 A spec proposal is open for simplifying the process of adding a path to the $PATH variable: [(devcontainers/spec#251)](https://github.com/devcontainers/spec/issues/251).
+
+To make testing for idempotency easy, [this change to the reference implementation](https://github.com/devcontainers/cli/pull/553) introduces a new mode to the `devcontainer features test` command that will attempt to install a Feature multiple times. This is useful for testing that a Feature is idempotent, and also for testing that a Feature is able to logically "juggle" multiple versions of a tool.
+
+## Writing your install script
+
+
+> 🔧 Many of the suggestions in this section may benefit from the [Feature library/code reuse proposal](https://github.com/devcontainers/spec/blob/main/proposals/features-library.md).
+
+This section includes some tips for the contents of the `install.sh` entrypoint script.
+
+### Detect Platform/OS
+
+> 🔧 A spec proposal is open for detecting the platform/OS and providing better warnings [(devcontainers/spec#58)](https://github.com/devcontainers/spec/issues/58).
+
+Features are often designed to work on a subset of possible base images. For example, the majority of Features in the [`devcontainers/features`](https://github.com/devcontainers/features) repo are designed to work broadly with debian-derived images. The limitation is often simply due to the wide array of base images available, and the fact that many Features will use an OS-specific package manager. To make it easy for users to understand which base images a Feature is designed to work with, it is recommended that Features include a check for the OS and provide a helpful error message if the OS is not supported.
+
+One possible way to implement this check is shown below.
+
+```bash
+# Source /etc/os-release to get OS info
+# Looks something like:
+# PRETTY_NAME="Debian GNU/Linux 11 (bullseye)"
+# NAME="Debian GNU/Linux"
+# VERSION_ID="11"
+# VERSION="11 (bullseye)"
+# VERSION_CODENAME=bullseye
+# ID=debian
+# HOME_URL="https://www.debian.org/"
+# SUPPORT_URL="https://www.debian.org/support"
+# BUG_REPORT_URL="https://bugs.debian.org/"
+. /etc/os-release
+# Store host architecture
+architecture="$(dpkg --print-architecture)"
+
+DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES="buster bullseye focal bionic xenial"
+if [[ "${DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES}" != *"${VERSION_CODENAME}"* ]]; then
+ print_error "Unsupported distribution version '${VERSION_CODENAME}'. To resolve, either: (1) set feature option '\"moby\": false' , or (2) choose a compatible OS distribution"
+ print_error "Supported distributions include: ${DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES}"
+ exit 1
+fi
+```
+
+If you are targeting distros that may not have your desired scripting language installed (eg: `bash` is often not installed on `alpine` images), you can either use plain `/bin/sh` - which is available virtually everywhere - or you can verify (and install) the scripting language in a small bootstrap script as shown below.
+
+```sh
+#!/bin/sh
+
+# ...
+# ...
+
+if [ "$(id -u)" -ne 0 ]; then
+ echo -e 'Script must be run as root. Use sudo, su, or add "USER root" to your Dockerfile before running this script.'
+ exit 1
+fi
+
+# If we're using Alpine, install bash before executing
+. /etc/os-release
+if [ "${ID}" = "alpine" ]; then
+ apk add --no-cache bash
+fi
+
+exec /bin/bash "$(dirname $0)/main.sh" "$@"
+exit $?
+```
+
+Validating functionality against several base images can be done by using the `devcontainer features test` command with the `--base-image` flag, or with a [scenario](https://github.com/devcontainers/cli/blob/main/docs/features/test.md#scenarios). For example, one could add a [workflow like this to their repo](https://github.com/devcontainers/features/blob/d934503a050ba84e6b42a006aacd891c4088eb62/.github/workflows/test-all.yaml#L9-L52).
+
+```yaml
+name: "Test Features matrixed with a set of base images"
+on:
+ push:
+ branches:
+ - main
+ workflow_dispatch:
+
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ continue-on-error: true
+ strategy:
+ matrix:
+ features: [
+ "anaconda",
+ "aws-cli",
+ "azure-cli",
+ # ...
+ ]
+ baseImage:
+ [
+ "ubuntu:bionic",
+ "ubuntu:focal",
+ "ubuntu:jammy",
+ "debian:11",
+ "debian:12",
+ "mcr.microsoft.com/devcontainers/base:ubuntu",
+ "mcr.microsoft.com/devcontainers/base:debian",
+ ]
+ steps:
+ - uses: actions/checkout@v3
+
+ - name: "Install latest devcontainer CLI"
+ run: npm install -g @devcontainers/cli
+ {% raw %}
+ - name: "Generating tests for '${{ matrix.features }}' against '${{ matrix.baseImage }}'"
+ run: devcontainer features test --skip-scenarios -f ${{ matrix.features }} -i ${{ matrix.baseImage }}
+ {% endraw %}
+```
+
+### Detect the non-root user
+
+Feature installation scripts are run as `root`. In contrast, many dev containers have a `remoteUser` set (either implicitly through [image metadata](https://containers.dev/implementors/spec/#image-metadata) or directly in the `devcontainer.json`). In a Feature's installation script, one should be mindful of the final user and account for instances where the user is not `root`.
+
+Feature authors should take advantage of the [`_REMOTE_USER` and similar variables](https://containers.dev/implementors/features/#user-env-var) injected during the build.
+
+```bash
+# Install tool in effective remoteUser's bin folder
+mkdir -p "$_REMOTE_USER_HOME/bin"
+curl $TOOL_DOWNLOAD_LINK -o "$_REMOTE_USER_HOME/bin/$TOOL"
+chown $_REMOTE_USER:$_REMOTE_USER "$_REMOTE_USER_HOME/bin/$TOOL"
+chmod 755 "$_REMOTE_USER_HOME/bin/$TOOL"
+```
+
+### Implement redundant paths/strategies
+
+Most Features in [the index today](https://containers.dev/features) have some external/upstream dependency. Very often these upstream dependencies can change (ie: versioning pattern, rotated GPG key, etc...) that may cause a Feature to fail to install. To mitigate this, one strategy is to implement multiple paths to install a given tool (if available). For example, a Feature that installs `go` might try to install it from the upstream package manager, and if not fall back to a GitHub release.
+
+Writing several [scenario tests](https://github.com/devcontainers/cli/blob/main/docs/features/test.md#scenarios) that force the Feature to go down distinct installation paths will help you catch cases where a given path no longer works.
\ No newline at end of file
diff --git a/_posts/2023-08-22-prebuild.md b/_posts/2023-08-22-prebuild.md
new file mode 100644
index 00000000..684e854c
--- /dev/null
+++ b/_posts/2023-08-22-prebuild.md
@@ -0,0 +1,138 @@
+---
+layout: post
+title: "Speed Up Your Workflow with Prebuilds"
+author:
+ - "@bamurtaugh"
+ - "@craiglpeters"
+authorUrl:
+ - "https://github.com/bamurtaugh"
+ - "https://github.com/craiglpeters"
+
+---
+
+Getting dev containers up and running for your projects is exciting - you've unlocked environments that include all the dependencies your projects need to run, and you can spend so much more time on coding rather than configuration.
+
+Once your dev container has everything it needs, you might start thinking more about ways to optimize it. For instance, it might take a while to build. Maybe it takes 5 minutes. Maybe it takes an hour!
+
+You can get back to working fast and productively after that initial container build, but what if you need to work on another machine and build the container again? Or what if some of your teammates want to use the container on their machines and will need to build it too? It'd be great to make the build time faster for everyone, every time.
+
+After configuring your dev container, a great next step is to **prebuild your image**.
+
+In this guide, we'll explore what it means to prebuild an image and the benefits of doing so, such as speeding up your workflow, simplifying your environment, and pinning to specific versions of tools.
+
+We have a variety of tools designed to help you with prebuilds. In this guide, we'll explore two different repos as examples of how our team uses different combinations of these tools:
+* The prebuilt image for the [Kubernetes repo](https://github.com/craiglpeters/kubernetes-devcontainer) developed by one of our spec maintainers [Craig](https://github.com/craiglpeters)
+* The prebuilt images we host in the [devcontainers/images](https://github.com/devcontainers/images/tree/main/src) repo as part of the dev container spec
+
+
+## What is prebuilding?
+
+We should first define: What is prebuilding?
+
+If you're already using dev containers, you're likely already familiar with the idea of building a container, where you package everything your app needs to run into a single unit.
+
+You need to build your container once it has all the dependencies it needs, and rebuild anytime you add new dependencies. Since you may not need to rebuild often, it might be alright if it takes a while for that initial build. But if you or your teammates need to use that container on another machine, you'll need to wait for it to build again in those new environments.
+
+> **Note:** The [dev container CLI doc](/implementors/reference#prebuilding) is another great resource on prebuilding.
+
+### Prebuilt Codespaces
+
+You may have heard (or will hear about) [GitHub Codespaces prebuilds](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds). Codespaces prebuilds are similar to prebuilt container images, with some additional focus on the other code in your repo.
+
+GitHub Codespaces prebuilds help to speed up the creation of new codespaces for large or complex repositories. A prebuild assembles the main components of a codespace for a particular combination of repository, branch, and `devcontainer.json` file.
+
+By default, whenever you push changes to your repository, GitHub Codespaces uses GitHub Actions to automatically update your prebuilds.
+
+You can learn more about codespaces prebuilds and how to manage them in the [codespaces docs](https://docs.github.com/en/codespaces/prebuilding-your-codespaces/about-github-codespaces-prebuilds).
+
+## How do I prebuild my image?
+
+We try to make prebuilding an image and using a prebuilt image as easy as possible. Let's walk through the couple of steps to get started.
+
+**Prebuilding an image:**
+* Install the [Dev Container CLI](/implementors/reference):
+
+ ```bash
+ npm install -g @devcontainers/cli
+ ```
+
+* Build your image and push it to a container registry (like the [Azure Container Registry](https://learn.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)):
+
+ ```bash
+ devcontainer build --workspace-folder . --push true --image-name {{ page.date | date_to_string }} - {{ page.author }}
+{{ page.date | date_to_string }} - + {% assign i = 0 %} + {% for a in page.author %} + {{ page.author[i] }} + {% assign i = i | plus:1 %} + {% endfor %} +
{{ content }} -
+ 
+
+
+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 6d0ac8dd..30a7d129 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,39 +29,45 @@ 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.
+
+You may learn more in the [announcement blog post](https://blog.jetbrains.com/idea/2023/06/intellij-idea-2023-2-eap-6/#SupportforDevContainers).
+
## Tools
### 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!
@@ -85,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
@@ -130,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 |
|----------|---------|----------------------|
@@ -145,8 +151,59 @@ 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
+
+[CodeSandbox](https://codesandbox.io/) provides cloud development environments running on a microVM architecture. VM specs start at 2 vCPUs + 2 GB RAM per environment (free tier) and can go up to 16 vCPUs + 32 GB RAM.
+
+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.
+
+#### Product specific properties
+CodeSandbox has built-in support for any programming language and supports Debian and Ubuntu-based images.
+
+All properties specific to CodeSandbox are placed within a `.codesandbox` folder at root level. Typically, this will contain a `tasks.json` file, which defines the commands to be run at startup or with a click.
+
+More details about these can be found in the CodeSandbox [documentation](https://codesandbox.io/docs/learn/repositories/task).
+
+#### 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}
+
+### 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.
+
+### Ona (formerly Gitpod)
+
+[Ona](https://ona.com/) (formerly Gitpod) is the mission control for software projects and software engineering agents. It provides secure, ephemeral development environments that run in our cloud or your VPC, enabling humans and agents to collaborate seamlessly.
+
+Ona fully adheres to the Dev Container Specification, so you can define portable and reproducible environments with `devcontainer.json`. Whether you’re onboarding a new developer, running background agents, or delegating long-running migrations, Ona Environments ensure every task runs in a clean, policy-enforced environment.
+
+For details on constraints, customization, and automation options, see the [Ona Dev Container docs](https://ona.com/docs/ona/configuration/devcontainer/overview).
+
### Schema
You can explore the [VS Code implementation](implementors/json_schema) of the dev container schema.
+
+
diff --git a/templates.html b/templates.html
index 089fe51c..14573146 100644
--- a/templates.html
+++ b/templates.html
@@ -17,18 +17,73 @@ 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 }} |