diff --git a/_implementors/contributing.md b/_implementors/contributing.md index 597847f..8fc2edb 100644 --- a/_implementors/contributing.md +++ b/_implementors/contributing.md @@ -19,7 +19,7 @@ Here is a sample: | Property | Type | Description | |:------------------|:------------|:------------| | `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 VS Code and other `devcontainer.json` supporting services / tools should use to create the dev container. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} - PRs to the [schema](https://github.com/microsoft/vscode/blob/main/extensions/configuration-editing/schemas/devContainer.schema.src.json), i.e code or shell scripts demonstrating approaches for implementation. diff --git a/_implementors/features-distribution.md b/_implementors/features-distribution.md index 77e0f2b..b01ac4c 100644 --- a/_implementors/features-distribution.md +++ b/_implementors/features-distribution.md @@ -81,7 +81,7 @@ The `devcontainer-collection.json` is an auto-generated metadata file. | :--- | :--- | :--- | | `sourceInformation` | object | Metadata from the implementing packaging tool. | | `features` | array | The list of features that are contained in this collection.| -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} Each Features's `devcontainer-feature.json` metadata file is appended into the `features` top-level array. diff --git a/_implementors/features.md b/_implementors/features.md index 9608b65..8c4ce51 100644 --- a/_implementors/features.md +++ b/_implementors/features.md @@ -57,7 +57,7 @@ The properties of the file are as follows: | `legacyIds` | array | Array of old IDs used to publish this Feature. The property is useful for renaming a currently published Feature within a single namespace. | | `deprecated` | boolean | Indicates that the Feature is deprecated, and will not receive any further updates/support. This property is intended to be used by the supporting tools for highlighting Feature deprecation. | | `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 .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`. @@ -73,7 +73,7 @@ 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 @@ -144,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 @@ -264,7 +264,7 @@ The `id` format specified dicates how a supporting tool will locate and download | `//[:]` | Reference to feature in OCI registry(*) | `ghcr.io/user/repo/go`
`ghcr.io/user/repo/go:1`
`ghcr.io/user/repo/go:latest`| | `https://` | Direct HTTPS URI to a tarball. | `https://github.com/user/repo/releases/devcontainer-feature-go.tgz` | | `./`| A relative directory(**) to folder containing a devcontainer-feature.json. | `./myGoFeature` | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} (*) OCI registry must implement the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec). Some implementors can be [found here](https://oras.land/implementors/). diff --git a/_implementors/json_reference.md b/_implementors/json_reference.md index 8c1f58d..05dcf95 100644 --- a/_implementors/json_reference.md +++ b/_implementors/json_reference.md @@ -34,7 +34,7 @@ Metadata properties marked with a 🏷️️ can be stored in the `devcontainer. | `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:
`"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 .table-responsive} +{: .table .table-bordered} ## Scenario specific properties @@ -55,7 +55,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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 @@ -65,7 +65,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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 @@ -84,7 +84,7 @@ When creating or working with a dev container, you may need different commands t | `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`. @@ -100,7 +100,7 @@ While `devcontainer.json` does not focus on hardware or VM provisioning, it can | `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,
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 .table-responsive} + {: .table .table-bordered} ## Port attributes @@ -113,7 +113,7 @@ The `portsAttributes` and `otherPortsAttributes` properties allow you to map def | `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 @@ -172,7 +172,7 @@ Variables can be referenced in certain string values in `devcontainer.json` in t | `${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 | 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 .table-responsive} +{: .table .table-bordered} ## Schema diff --git a/_implementors/spec.md b/_implementors/spec.md index 304125b..ecd0600 100644 --- a/_implementors/spec.md +++ b/_implementors/spec.md @@ -91,7 +91,7 @@ To apply the metadata together with a user's `devcontainer.json` at runtime, the | `shutdownAction` | `string` (enum) | Last value wins. | ✓ | | | `updateRemoteUserUID` | `boolean` | Last value wins. | ✓ | | | `hostRequirements` | `cpus`, `memory`, `storage`, `gpu` | Max value wins. | ✓ | | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} Variables in string values will be substituted at the time the value is applied. When the order matters, the `devcontainer.json` is considered last. diff --git a/_implementors/templates-distribution.md b/_implementors/templates-distribution.md index da2ad7a..3e96eb5 100644 --- a/_implementors/templates-distribution.md +++ b/_implementors/templates-distribution.md @@ -78,7 +78,7 @@ The `devcontainer-collection.json` is an auto-generated metadata file. | :--- | :--- | :--- | | `sourceInformation` | object | Metadata from the implementing packaging tool. | | `templates` | array | The list of Templates that are contained in this collection.| -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} Each Template's `devcontainer-template.json` metadata file is appended into the `templates` top-level array. diff --git a/_implementors/templates.md b/_implementors/templates.md index 681a48c..8a0a519 100644 --- a/_implementors/templates.md +++ b/_implementors/templates.md @@ -42,7 +42,7 @@ The properties of the file are as follows: | `publisher` | string | Name of the publisher/maintainer of the Template. | | `keywords` | array | List of strings relevant to a user that would search for this Template. | | [`optionalPaths`](#optionalPaths) | array | An array of files or directories that tooling may consider "optional" when applying a Template. Directories are indicated with a trailing `/*`, (eg: `.github/*`). -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} ### The `options` property The `options` property contains a map of option IDs and their related configuration settings. These `options` are used by the supporting tools to prompt the user to choose from different Template configuration options. The tools would replace the option ID with the selected value in all the files (within the sub-directory of the Template). This replacement would happen before dropping the `.devcontainer.json` (or `.devcontainer/devcontainer.json`) and other files (within the sub-directory of the Template) required to containerize your project. See [option resolution](#option-resolution) for more details. For example: @@ -68,7 +68,7 @@ The `options` property contains a map of option IDs and their related configurat | `optionId.proposals` | array | A list of suggested string values. Free-form values **are** allowed. Omit when using `optionId.enum`. | | `optionId.enum` | array | A strict list of allowed string values. Free-form values are **not** allowed. Omit when using `optionId.proposals`. | | `optionId.default` | string | Default value for the option. | -{: .table .table-bordered .table-responsive} +{: .table .table-bordered} > `Note`: The `options` must be unique for every `devcontainer-template.json` diff --git a/supporting.md b/supporting.md index 766eb2c..969dd8b 100644 --- a/supporting.md +++ b/supporting.md @@ -29,7 +29,7 @@ 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. @@ -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 @@ -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 @@ -187,7 +187,7 @@ The following properties apply differently to CodeSandbox. | `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