From 8a7cecf3a24217c9f20ad5bdd423a2fe8baa34d1 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 10:59:21 -0800 Subject: [PATCH 01/28] Add devcontainer.json reference --- docs/devcontainerjson-reference.md | 172 +++++++++++++++++++++++++++++ 1 file changed, 172 insertions(+) create mode 100644 docs/devcontainerjson-reference.md diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md new file mode 100644 index 00000000..22b59663 --- /dev/null +++ b/docs/devcontainerjson-reference.md @@ -0,0 +1,172 @@ +# devcontainer.json reference + +A `devcontainer.json` file in your project tells Visual Studio Code (and other services and tools that support the format) how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). + +[Set up a folder to run in a container](https://code.visualstudio.com/docs/remote/create-dev-container#_set-up-a-folder-to-run-in-a-container) has more information on configuring a dev container or you can use the **Remote-Containers: Add Development Container Configuration Files...** or **Codespaces: Add Development Container Configuration Files...** commands from the Command Palette (`kbstyle(F1)`) to add a wide variety of base configurations from the [vscode-dev-containers repository](https://github.com/microsoft/vscode-dev-containers/tree/main/containers). + +> **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** or **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. + +## Scenario specific properties + +The focus of `devcontainer.json` is to describe how to enrich a container for the purposes of development rather than acting as a multi-container orchestrator format. Instead, container orchestrator formats can be referenced when needed to manage multiple containers and their lifecycles. Today, `devcontainer.json` includes scenario specific properties for working without a container orchestrator (by directly referencing an image or Dockerfile) and for using Docker Compose as a simple multi-container orchestrator. + +### Image or Dockerfile specific properties + +| Property | Type | Description | +|----------|------|-------------| +| `image` | string | **Required** when [using an image](https://code.visualstudio.com/docs/remote/create-dev-container#_using-an-image-or-dockerfile). 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` / `dockerFile` | string |**Required** when [using a Dockerfile](https://code.visualstudio.com/docs/remote/create-dev-container#_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. You can find Dockerfiles for different runtimes in the [vscode-dev-containers repository](https://github.com/microsoft/vscode-dev-containers/tree/main/containers). | +| `build.context` / `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.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](https://code.visualstudio.com/docs/remote/containers#_always-forwarding-a-port). This property accepts a port or array of ports that should be [published](https://code.visualstudio.com/docs/remote/containers#_publishing-a-port) 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 `[]`. | +| `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | +| `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | +| `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]`

⚠️ Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| +| `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). Primarily useful for [configuring remote containers](https://code.visualstudio.com/remote/advancedcontainers/develop-remote-host) or [improving disk performance](https://code.visualstudio.com/remote/advancedcontainers/improve-performance). 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"`

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | +| `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.

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | +| `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" ]` . | + +### Docker Compose specific properties + +| Property | Type | Description | +|----------|------|-------------| +| `dockerComposeFile` | string,
array | **Required** when [using Docker Compose](https://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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://code.visualstudio.com/docs/remote/create-dev-container#_extend-your-docker-compose-file-for-development). 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. | +| `service` | string | **Required** when [using Docker Compose](https://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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 `"/"`. | + +## General devcontainer.json properties + +| Property | Type | Description | +|----------|------|-------------| +| `name` | string | A name for the dev container displayed in the UI. | +| `forwardPorts` | array | An array of port numbers or `"host:port"` values (e.g. `[3000, "db:5432"]`) that should always be forwarded from inside the primary container to the local machine (including on the web for Codespaces). The property is most useful for forwarding ports that cannot be auto-forwarded because the related process that starts before the `devcontainer.json` supporting service / tool connects or for forwarding a service not in the primary container in Docker Compose scenarios (e.g. `"db:5432"`). Defaults to `[]`.

⚠️ Codespaces does not yet support the `"host:port"` variation of this property. | +| `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}`

⚠️ Codespaces does not yet support the `"host:port"` variation of this property.| +| `otherPortsAttributes` | object | Default options for ports, port ranges, and hosts that aren't configured using `portsAttributes`. See [port attributes](#port-attributes) for available options. For example:
`"otherPortsAttributes": {"onAutoForward": "silent"}` | +| `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for the `devcontainer.json` supporting service / tool (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. Be sure **Terminal > Integrated: Inherit Env** is checked in settings or the variables will not appear in the terminal. For example:
`"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path", "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded) | +| `remoteUser` | string | Overrides the user that `devcontainer.json` supporting services tools / runs as in the container (along with sub-processes like terminals, tasks, or debugging). Does not change the user the container as a whole runs as which can be set using `containerUser` for images and Dockerfiles or [in your Docker Compose file](https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir) instead. Defaults to the user the container as a whole is running as (often `root`).
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded). | +| `updateRemoteUserUID` | boolean | On Linux, if `containerUser` or `remoteUser` is specified, the container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts. Defaults to `true`.
Requires the container be recreated / rebuilt for updates to take effect. | +| `userEnvProbe` | enum | Indicates the type of shell to use to "probe" for user environment variables to include in `devcontainer.json` supporting services' / tools' processes: `none`, `interactiveShell`, `loginShell`, or `loginInteractiveShell` (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in `/etc/bash.bashrc` and `~/.bashrc` while login shells usually include variables from `/etc/profile` and `~/.profile`. Setting this property to `loginInteractiveShell` will get variables from all four files. | +| `overrideCommand` | boolean | Tells `devcontainer.json` supporting services / tools whether they should run `/bin/sh -c "while sleep 1000; do :; done"` when starting the container instead of the container's default command (since the container can shut down if the default command fails). Set to `false` if the default command must run for the container to function properly. Defaults to `true` for when using an image Dockerfile and `false` when referencing a Docker Compose file. | +| `features` | object | An object of [dev container features](https://code.visualstudio.com/docs/remote/containers#_dev-container-features-preview) 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | +| `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose).

⚠️ Does not apply to Codespaces. | + +## VS Code specific properties + +While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to VS Code. + +| Property | Type | Description | +|----------|------|-------------| +| `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 `{}`. | +| `devPort` | integer | Allows you to force a specific port that VS Code Server should use in the container. Defaults to a random, available port. | + +## Lifecycle scripts + +When creating or working with a dev container, you may need different commands to be run at different points in the container's lifecycle. The table below lists a set of command properties you can use to update what the container's contents in the order in which they are run (for example, `onCreateCommand` will run after `initializeCommand`). Each command property is an string or list of command arguments that should execute from the `workspaceFolder`. + +| Property | Type | Description | +|----------|------|-------------| +| `initializeCommand` | string,
array | 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 Codespaces, this is in the cloud. | +| `onCreateCommand` | string,
array | 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.

GitHub Codespaces also use this command when generating prebuilt codespaces, but it executes before the container has been assigned to a specific user. It therefore can only take advantage of repository and org scoped secrets or permissions.| +| `updateContentCommand` | string,
array | 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 GitHub Codespaces will also periodically execute the command to refresh available prebuilt codespaces. Like `onCreateCommand` in GitHub Codespaces, it can only take advantage of repository and org scoped secrets or permissions. | +| `postCreateCommand` | string,
array | 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.

In GitHub Codespaces, this command can always take advantage of user specific secrets and permissions. | +| `postStartCommand` | string,
array | A command to run each time the container is successfully started. | +| `postAttachCommand` | string,
array | A command to run each time a tool has successfully attached to the container. | +| `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. | + +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` + +If one of the lifecycle scripts fails, any subsequent scripts will not be executed. For instance, if `postCreateCommand` fails, `postStartCommand` and any following scripts will be skipped. + +## Minimum host requirements + +While `devcontainer.json` does not focus on hardware or VM provisioning, it can be useful to know your container's minimum RAM, CPU, and storage requirements. This is what the `hostRequirements` properties allow you to do. Cloud services like GitHub Codespaces use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. + +| Property | Type | Description | +|----------|------|-------------| +| `hostRequirements.cpus` | integer | Indicates the minimum required number of CPUs / virtual CPUs / cores. For example: `"hostRequirements": {"cpus": 2}` | +| `hostRequirements.memory` | string | A string indicating minimum memory requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"memory": "4gb"}` | +| `hostRequirements.storage` | string | A string indicating minimum storage requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"storage": "32gb"}` | + +## Port attributes + +The `portsAttributes` and `otherPortsAttributes` properties allow you to map default port options for one or more manually or automatically forwarded ports. The following is a list of options that can be set in the configuration object assigned to the property. + +| Property | Type | Description | +|----------|------|-------------| +| `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 Codespaces 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 `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`. | + +## Formatting string vs. array properties + +The format of certain properties will vary depending on the involvement of a shell. + +`postCreateCommand`, `postStartCommand`, `postAttachCommand`, and `initializeCommand` all have an array and a string type, while `runArgs` only has the array type. An array is passed to the OS for execution without going through a shell, whereas a string goes through a shell (it needs to be parsed into command and arguments). + +Using `runArgs` via a typical command line, you'll need single quotes if the shell runs into parameters with spaces. However, these single quotes aren't passed on to the executable. Thus, in your `devcontainer.json`, you'd follow the array format and leave out the single quotes: + +```json +"runArgs": ["--device-cgroup-rule=my rule here"] +``` + +Rather than: + +```json +"runArgs": ["--device-cgroup-rule='my rule here'"] +``` + +We can compare the string and the array versions of `postAttachCommand` as well. You can use the following string format, which will remove the single quotes as part of the shell's parsing: + +```json +"postAttachCommand": "echo foo='bar'" +``` + +By contrast, the array format will keep the single quotes and write them to standard out (you can see the output in the dev container log): + +```json +"postAttachCommand": ["echo", "foo='bar'"] +``` + +## Variables in devcontainer.json + +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. + +| 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. To 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}" }`

⚠️ For Codespaces, the host is in the cloud rather than your local machine.| +| `${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" }` | +| `${localWorkspaceFolder}` | Any | Path of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `${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`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | + +## Attached container configuration reference + +[Attached container configuration files](https://code.visualstudio.com/docs/remote/attach-container#_attached-container-configuration-files) are similar to `devcontainer.json` and supports a subset of its properties. + +| Property | Type | Description | +|----------|------|-------------| +| `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). Not set by default (an empty window is opened). | +| `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. | +| `forwardPorts` | array | A list of ports that should be forwarded from inside the container to the local machine. | +| `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}` | +| `otherPortsAttributes` | object | Default options for ports, port ranges, and hosts that aren't configured using `portsAttributes`. See [port attributes](#port-attributes) for available options. For example:
`"otherPortsAttributes": {"onAutoForward": "silent"}` | +| `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for `devcontainer.json` supporting services / tools (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-attached-container-configuration-files) may be referenced in the values.
For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | +| `remoteUser` | string | Overrides the user that the `devcontainer.json` supporting service / tool runs as in the container (along with sub-processes like terminals, tasks, or debugging). Defaults to the user the container as a whole is running as (often `root`). | +| `userEnvProbe` | enum | Indicates the type of shell to use to "probe" for user environment variables to include in the connected tool's processes: `none`, `interactiveShell`, `loginShell`, or `loginInteractiveShell` (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in `/etc/bash.bashrc` and `~/.bashrc` while login shells usually include variables from `/etc/profile` and `~/.profile`. Setting this property to `loginInteractiveShell` will get variables from all four files. | +| `postAttachCommand` | string,
array | A command string or list of command arguments to run after the `devcontainer.json` supporting service / tool attaches to the container. 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. Not set by default. | + +### Variables in attached container configuration files + +Variables can be referenced in certain string values in attached configuration files in the following format: **${variableName}**. The following table is a list of available variables you can use. + +| Variable | Properties | Description | +|----------|---------|----------------------| +| `${containerEnv:VAR_NAME}` | `remoteEnv` | Value of an existing environment variable inside the container (in this case, `VAR_NAME`) once it is up and running. For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | \ No newline at end of file From c1da2bc2678762893c3fdee7b08b6bb17f250e8f Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Tue, 15 Feb 2022 11:07:29 -0800 Subject: [PATCH 02/28] Update devcontainerjson-reference.md --- docs/devcontainerjson-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 22b59663..d975469b 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -1,6 +1,6 @@ # devcontainer.json reference -A `devcontainer.json` file in your project tells Visual Studio Code (and other services and tools that support the format) how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). +A `devcontainer.json` file in your project tells `devcontainer.json` supporting services / tools how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). [Set up a folder to run in a container](https://code.visualstudio.com/docs/remote/create-dev-container#_set-up-a-folder-to-run-in-a-container) has more information on configuring a dev container or you can use the **Remote-Containers: Add Development Container Configuration Files...** or **Codespaces: Add Development Container Configuration Files...** commands from the Command Palette (`kbstyle(F1)`) to add a wide variety of base configurations from the [vscode-dev-containers repository](https://github.com/microsoft/vscode-dev-containers/tree/main/containers). @@ -169,4 +169,4 @@ Variables can be referenced in certain string values in attached configuration f | Variable | Properties | Description | |----------|---------|----------------------| -| `${containerEnv:VAR_NAME}` | `remoteEnv` | Value of an existing environment variable inside the container (in this case, `VAR_NAME`) once it is up and running. For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | \ No newline at end of file +| `${containerEnv:VAR_NAME}` | `remoteEnv` | Value of an existing environment variable inside the container (in this case, `VAR_NAME`) once it is up and running. For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | From b7197e7087dc4e7867c9180f34fa28c7416f701a Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:23:38 -0800 Subject: [PATCH 03/28] Feedback --- docs/devcontainerjson-reference.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index d975469b..6d6cb9cf 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -1,8 +1,6 @@ # devcontainer.json reference -A `devcontainer.json` file in your project tells `devcontainer.json` supporting services / tools how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). - -[Set up a folder to run in a container](https://code.visualstudio.com/docs/remote/create-dev-container#_set-up-a-folder-to-run-in-a-container) has more information on configuring a dev container or you can use the **Remote-Containers: Add Development Container Configuration Files...** or **Codespaces: Add Development Container Configuration Files...** commands from the Command Palette (`kbstyle(F1)`) to add a wide variety of base configurations from the [vscode-dev-containers repository](https://github.com/microsoft/vscode-dev-containers/tree/main/containers). +A `devcontainer.json` file in your project tells tools / services that support the dev container spec how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). > **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** or **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. @@ -15,8 +13,8 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | Property | Type | Description | |----------|------|-------------| | `image` | string | **Required** when [using an image](https://code.visualstudio.com/docs/remote/create-dev-container#_using-an-image-or-dockerfile). 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` / `dockerFile` | string |**Required** when [using a Dockerfile](https://code.visualstudio.com/docs/remote/create-dev-container#_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. You can find Dockerfiles for different runtimes in the [vscode-dev-containers repository](https://github.com/microsoft/vscode-dev-containers/tree/main/containers). | -| `build.context` / `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.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.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`. From 67bb0652265bd3c008d191a8a51d96f272504e5b Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:28:51 -0800 Subject: [PATCH 04/28] Add ports info --- docs/devcontainerjson-reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 6d6cb9cf..f5ebb457 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -18,7 +18,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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.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](https://code.visualstudio.com/docs/remote/containers#_always-forwarding-a-port). This property accepts a port or array of ports that should be [published](https://code.visualstudio.com/docs/remote/containers#_publishing-a-port) 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 `[]`. | +| `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-devcontainerjson-properties). This property accepts a port or array of ports that should be published locally when the container is running.
Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application.
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 `[]`. | | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | | `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]`

⚠️ Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| From 06c14a7356f50fdc5d9d2952fbba83f728e86f97 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:31:36 -0800 Subject: [PATCH 05/28] Ports section --- docs/devcontainerjson-reference.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index f5ebb457..c5275548 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -18,7 +18,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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.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-devcontainerjson-properties). This property accepts a port or array of ports that should be published locally when the container is running.
Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application.
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 `[]`. | +| `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-devcontainerjson-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). | | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | | `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]`

⚠️ Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| @@ -26,6 +26,10 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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.

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | | `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" ]` . | +#### Publishing vs forwarding ports + +Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application. + ### Docker Compose specific properties | Property | Type | Description | From d393cb2dfd44e0a7fb7c30bed9a805230685c0e8 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:37:40 -0800 Subject: [PATCH 06/28] Updates --- docs/devcontainerjson-reference.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index c5275548..7c8d6e10 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -22,7 +22,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | | `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]`

⚠️ Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| -| `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). Primarily useful for [configuring remote containers](https://code.visualstudio.com/remote/advancedcontainers/develop-remote-host) or [improving disk performance](https://code.visualstudio.com/remote/advancedcontainers/improve-performance). 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"`

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | +| `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"`

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | | `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.

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | | `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" ]` . | @@ -47,12 +47,12 @@ Docker has the concept of "publishing" ports when the container is created. Publ | `forwardPorts` | array | An array of port numbers or `"host:port"` values (e.g. `[3000, "db:5432"]`) that should always be forwarded from inside the primary container to the local machine (including on the web for Codespaces). The property is most useful for forwarding ports that cannot be auto-forwarded because the related process that starts before the `devcontainer.json` supporting service / tool connects or for forwarding a service not in the primary container in Docker Compose scenarios (e.g. `"db:5432"`). Defaults to `[]`.

⚠️ Codespaces does not yet support the `"host:port"` variation of this property. | | `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}`

⚠️ Codespaces does not yet support the `"host:port"` variation of this property.| | `otherPortsAttributes` | object | Default options for ports, port ranges, and hosts that aren't configured using `portsAttributes`. See [port attributes](#port-attributes) for available options. For example:
`"otherPortsAttributes": {"onAutoForward": "silent"}` | -| `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for the `devcontainer.json` supporting service / tool (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. Be sure **Terminal > Integrated: Inherit Env** is checked in settings or the variables will not appear in the terminal. For example:
`"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path", "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded) | +| `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for the `devcontainer.json` supporting service / tool (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values.
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded) | | `remoteUser` | string | Overrides the user that `devcontainer.json` supporting services tools / runs as in the container (along with sub-processes like terminals, tasks, or debugging). Does not change the user the container as a whole runs as which can be set using `containerUser` for images and Dockerfiles or [in your Docker Compose file](https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir) instead. Defaults to the user the container as a whole is running as (often `root`).
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded). | | `updateRemoteUserUID` | boolean | On Linux, if `containerUser` or `remoteUser` is specified, the container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts. Defaults to `true`.
Requires the container be recreated / rebuilt for updates to take effect. | | `userEnvProbe` | enum | Indicates the type of shell to use to "probe" for user environment variables to include in `devcontainer.json` supporting services' / tools' processes: `none`, `interactiveShell`, `loginShell`, or `loginInteractiveShell` (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in `/etc/bash.bashrc` and `~/.bashrc` while login shells usually include variables from `/etc/profile` and `~/.profile`. Setting this property to `loginInteractiveShell` will get variables from all four files. | | `overrideCommand` | boolean | Tells `devcontainer.json` supporting services / tools whether they should run `/bin/sh -c "while sleep 1000; do :; done"` when starting the container instead of the container's default command (since the container can shut down if the default command fails). Set to `false` if the default command must run for the container to function properly. Defaults to `true` for when using an image Dockerfile and `false` when referencing a Docker Compose file. | -| `features` | object | An object of [dev container features](https://code.visualstudio.com/docs/remote/containers#_dev-container-features-preview) 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | +| `features` (currently in preview) | object | An object of dev container 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | | `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose).

⚠️ Does not apply to Codespaces. | ## VS Code specific properties @@ -63,7 +63,6 @@ While most properties apply to any `devcontainer.json` supporting tool or servic |----------|------|-------------| | `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 `{}`. | -| `devPort` | integer | Allows you to force a specific port that VS Code Server should use in the container. Defaults to a random, available port. | ## Lifecycle scripts From 32cc5a139db4531e7ca60a993a676e8ab5b2266a Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:40:56 -0800 Subject: [PATCH 07/28] Lifecycle updates --- docs/devcontainerjson-reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 7c8d6e10..bc4968db 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -70,10 +70,10 @@ When creating or working with a dev container, you may need different commands t | Property | Type | Description | |----------|------|-------------| -| `initializeCommand` | string,
array | 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 Codespaces, this is in the cloud. | -| `onCreateCommand` | string,
array | 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.

GitHub Codespaces also use this command when generating prebuilt codespaces, but it executes before the container has been assigned to a specific user. It therefore can only take advantage of repository and org scoped secrets or permissions.| -| `updateContentCommand` | string,
array | 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 GitHub Codespaces will also periodically execute the command to refresh available prebuilt codespaces. Like `onCreateCommand` in GitHub Codespaces, it can only take advantage of repository and org scoped secrets or permissions. | -| `postCreateCommand` | string,
array | 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.

In GitHub Codespaces, this command can always take advantage of user specific secrets and permissions. | +| `initializeCommand` | string,
array | 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. | +| `onCreateCommand` | string,
array | 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. | +| `updateContentCommand` | string,
array | 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. | +| `postCreateCommand` | string,
array | 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. | | `postStartCommand` | string,
array | A command to run each time the container is successfully started. | | `postAttachCommand` | string,
array | A command to run each time a tool has successfully attached to the container. | | `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. | From 647f3c70b7705f13b626554258a4257acf726aa5 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:42:34 -0800 Subject: [PATCH 08/28] Updates --- docs/devcontainerjson-reference.md | 29 ++--------------------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index bc4968db..94852e53 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -84,7 +84,7 @@ If one of the lifecycle scripts fails, any subsequent scripts will not be execut ## Minimum host requirements -While `devcontainer.json` does not focus on hardware or VM provisioning, it can be useful to know your container's minimum RAM, CPU, and storage requirements. This is what the `hostRequirements` properties allow you to do. Cloud services like GitHub Codespaces use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. +While `devcontainer.json` does not focus on hardware or VM provisioning, it can be useful to know your container's minimum RAM, CPU, and storage requirements. This is what the `hostRequirements` properties allow you to do. Cloud services can use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. | Property | Type | Description | |----------|------|-------------| @@ -145,29 +145,4 @@ Variables can be referenced in certain string values in `devcontainer.json` in t | `${localWorkspaceFolder}` | Any | Path of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | | `${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`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | -| `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | - -## Attached container configuration reference - -[Attached container configuration files](https://code.visualstudio.com/docs/remote/attach-container#_attached-container-configuration-files) are similar to `devcontainer.json` and supports a subset of its properties. - -| Property | Type | Description | -|----------|------|-------------| -| `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). Not set by default (an empty window is opened). | -| `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. | -| `forwardPorts` | array | A list of ports that should be forwarded from inside the container to the local machine. | -| `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}` | -| `otherPortsAttributes` | object | Default options for ports, port ranges, and hosts that aren't configured using `portsAttributes`. See [port attributes](#port-attributes) for available options. For example:
`"otherPortsAttributes": {"onAutoForward": "silent"}` | -| `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for `devcontainer.json` supporting services / tools (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-attached-container-configuration-files) may be referenced in the values.
For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | -| `remoteUser` | string | Overrides the user that the `devcontainer.json` supporting service / tool runs as in the container (along with sub-processes like terminals, tasks, or debugging). Defaults to the user the container as a whole is running as (often `root`). | -| `userEnvProbe` | enum | Indicates the type of shell to use to "probe" for user environment variables to include in the connected tool's processes: `none`, `interactiveShell`, `loginShell`, or `loginInteractiveShell` (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in `/etc/bash.bashrc` and `~/.bashrc` while login shells usually include variables from `/etc/profile` and `~/.profile`. Setting this property to `loginInteractiveShell` will get variables from all four files. | -| `postAttachCommand` | string,
array | A command string or list of command arguments to run after the `devcontainer.json` supporting service / tool attaches to the container. 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. Not set by default. | - -### Variables in attached container configuration files - -Variables can be referenced in certain string values in attached configuration files in the following format: **${variableName}**. The following table is a list of available variables you can use. - -| Variable | Properties | Description | -|----------|---------|----------------------| -| `${containerEnv:VAR_NAME}` | `remoteEnv` | Value of an existing environment variable inside the container (in this case, `VAR_NAME`) once it is up and running. For example: `"remoteEnv": { "PATH": "${containerEnv:PATH}:/some/other/path" }` | +| `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | \ No newline at end of file From b99bd7ee812b32ed7958b166557aee332467566a Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 15 Feb 2022 15:54:12 -0800 Subject: [PATCH 09/28] Supporting tools --- docs/devcontainerjson-reference.md | 4 +--- docs/supporting-tools.md | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 3 deletions(-) create mode 100644 docs/supporting-tools.md diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 94852e53..1c92cdcf 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -1,8 +1,6 @@ # devcontainer.json reference -A `devcontainer.json` file in your project tells tools / services that support the dev container spec how to access (or create) a **development container** with a well-defined tool and runtime stack. It's currently supported by the [Remote - Containers](https://aka.ms/vscode-remote/download/containers) extension and [GitHub Codespaces](https://github.com/features/codespaces). - -> **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** or **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. +A `devcontainer.json` file in your project tells [tools and services that support the dev container spec](/docs/supporting-tools.md) how to access (or create) a **development container** with a well-defined tool and runtime stack. ## Scenario specific properties diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md new file mode 100644 index 00000000..0982de04 --- /dev/null +++ b/docs/supporting-tools.md @@ -0,0 +1,25 @@ +# Supporting tools and services + +A `devcontainer.json` file in your project tells tools and services that support the dev container spec how to access (or create) a **development container** with a well-defined tool and runtime stack. + +This document outlines tools and services that currently support this format. + +## Remote - Containers + +The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. + +> **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. + +## GitHub Codespaces + +A [codespace](https://docs.github.com/en/codespaces/overview) is a development environment that's hosted in the cloud. Codespaces run on a variety of VM-based compute options hosted by GitHub.com, which you can configure from 2 core machines up to 32 core machines. You can connect to your codespaces from the browser or locally using Visual Studio Code. + +> **Tip:** If you've already built a container and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. + +## devcontainer CLI + +Given the growing number of use cases for dev containers, there is a companion [devcontainer command line interface](https://code.visualstudio.com/docs/remote/devcontainer-cli) (CLI) that can be used independent of the Remote - Containers extension or GitHub Codespaces. + +## 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). \ No newline at end of file From 8405d34a43e01c06b7551cca6171d7b0b089d1ce Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 16 Feb 2022 10:48:45 -0800 Subject: [PATCH 10/28] Tool-specific section --- docs/devcontainerjson-reference.md | 9 ++------- docs/supporting-tools.md | 14 ++++++++++++-- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 1c92cdcf..836c1b39 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -53,14 +53,9 @@ Docker has the concept of "publishing" ports when the container is created. Publ | `features` (currently in preview) | object | An object of dev container 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | | `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose).

⚠️ Does not apply to Codespaces. | -## VS Code specific properties +## Tool-specific properties -While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to VS Code. - -| Property | Type | Description | -|----------|------|-------------| -| `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 `{}`. | +While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. You may explore this in the [supporting tools and services document](/docs/supporting-tools.md/#tool-specific-properties). ## Lifecycle scripts diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index 0982de04..a22bd010 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -4,7 +4,7 @@ A `devcontainer.json` file in your project tells tools and services that support This document outlines tools and services that currently support this format. -## Remote - Containers +## Visual Studio Code Remote - Containers The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. @@ -22,4 +22,14 @@ Given the growing number of use cases for dev containers, there is a companion [ ## 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). \ No newline at end of file +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). + +## Tool-specific properties +While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. + +### VS Code specific properties + +| Property | Type | Description | +|----------|------|-------------| +| `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 `{}`. | \ No newline at end of file From 1d401320fa511389ce368e7e2c32ed7d8022a9aa Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 16 Feb 2022 10:51:12 -0800 Subject: [PATCH 11/28] Update headings --- docs/supporting-tools.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index a22bd010..b26ceabe 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -27,9 +27,14 @@ You can see the VS Code implementation of the dev container schema [here](https: ## Tool-specific properties While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. -### VS Code specific properties +### VS Code | Property | Type | Description | |----------|------|-------------| | `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 `{}`. | \ No newline at end of file +| `settings` | object | Adds default `settings.json` values into a container/machine specific settings file. Defaults to `{}`. | + +### GitHub Codespaces + +Certain properties work differently in Codespaces than other tools. + From 3bf4aeee2da748cece00889caa1b5b5260265672 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 16 Feb 2022 10:54:32 -0800 Subject: [PATCH 12/28] Codespaces content --- docs/supporting-tools.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index b26ceabe..bb118a6f 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -38,3 +38,12 @@ While most properties apply to any `devcontainer.json` supporting tool or servic Certain properties work differently in Codespaces than other tools. +| Property or variable | Type | Description | +|----------|---------|----------------------| +| `mounts` | array | Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| +| `workspaceMount` | string | Not yet supported in Codespaces. | +| `workspaceFolder` | string | Not yet supported in Codespaces. | +| `forwardPorts` | array | Codespaces does not yet support the `"host:port"` variation of this property. | +| `portsAttributes` | object | Codespaces does not yet support the `"host:port"` variation of this property.| +| `shutdownAction` | enum | Does not apply to Codespaces. | +| `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| \ No newline at end of file From c3b598f97930e2e1b54e0785aa656370a6ef2053 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 16 Feb 2022 10:56:24 -0800 Subject: [PATCH 13/28] Update specific wording --- docs/devcontainerjson-reference.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index 836c1b39..ba23e3ab 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -19,9 +19,9 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-devcontainerjson-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). | | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | -| `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]`

⚠️ Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| -| `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"`

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | -| `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.

⚠️ Not yet supported in Codespaces or when using Clone Repository in Container Volume. | +| `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]` | +| `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"`

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `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.

⚠️ Not yet supported when using Clone Repository in Container Volume. | | `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" ]` . | #### Publishing vs forwarding ports @@ -42,8 +42,8 @@ Docker has the concept of "publishing" ports when the container is created. Publ | Property | Type | Description | |----------|------|-------------| | `name` | string | A name for the dev container displayed in the UI. | -| `forwardPorts` | array | An array of port numbers or `"host:port"` values (e.g. `[3000, "db:5432"]`) that should always be forwarded from inside the primary container to the local machine (including on the web for Codespaces). The property is most useful for forwarding ports that cannot be auto-forwarded because the related process that starts before the `devcontainer.json` supporting service / tool connects or for forwarding a service not in the primary container in Docker Compose scenarios (e.g. `"db:5432"`). Defaults to `[]`.

⚠️ Codespaces does not yet support the `"host:port"` variation of this property. | -| `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}`

⚠️ Codespaces does not yet support the `"host:port"` variation of this property.| +| `forwardPorts` | array | An array of port numbers or `"host:port"` values (e.g. `[3000, "db:5432"]`) that should always be forwarded from inside the primary container to the local machine (including on the web). The property is most useful for forwarding ports that cannot be auto-forwarded because the related process that starts before the `devcontainer.json` supporting service / tool connects or for forwarding a service not in the primary container in Docker Compose scenarios (e.g. `"db:5432"`). Defaults to `[]`. | +| `portsAttributes` | object | Object that maps a port number, `"host:port"` value, range, or regular expression to a set of default options. See [port attributes](#port-attributes) for available options. For example:
`"portsAttributes": {"3000": {"label": "Application port"}}` | | `otherPortsAttributes` | object | Default options for ports, port ranges, and hosts that aren't configured using `portsAttributes`. See [port attributes](#port-attributes) for available options. For example:
`"otherPortsAttributes": {"onAutoForward": "silent"}` | | `remoteEnv` | object | A set of name-value pairs that sets or overrides environment variables for the `devcontainer.json` supporting service / tool (or sub-processes like terminals) but not the container as a whole. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values.
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded) | | `remoteUser` | string | Overrides the user that `devcontainer.json` supporting services tools / runs as in the container (along with sub-processes like terminals, tasks, or debugging). Does not change the user the container as a whole runs as which can be set using `containerUser` for images and Dockerfiles or [in your Docker Compose file](https://docs.docker.com/compose/compose-file/#domainname-hostname-ipc-mac_address-privileged-read_only-shm_size-stdin_open-tty-user-working_dir) instead. Defaults to the user the container as a whole is running as (often `root`).
Updates are applied when the `devcontainer.json` supporting service / tool is restarted (or the window is reloaded). | @@ -51,7 +51,7 @@ Docker has the concept of "publishing" ports when the container is created. Publ | `userEnvProbe` | enum | Indicates the type of shell to use to "probe" for user environment variables to include in `devcontainer.json` supporting services' / tools' processes: `none`, `interactiveShell`, `loginShell`, or `loginInteractiveShell` (default). The specific shell used is based on the default shell for the user (typically bash). For example, bash interactive shells will typically include variables set in `/etc/bash.bashrc` and `~/.bashrc` while login shells usually include variables from `/etc/profile` and `~/.profile`. Setting this property to `loginInteractiveShell` will get variables from all four files. | | `overrideCommand` | boolean | Tells `devcontainer.json` supporting services / tools whether they should run `/bin/sh -c "while sleep 1000; do :; done"` when starting the container instead of the container's default command (since the container can shut down if the default command fails). Set to `false` if the default command must run for the container to function properly. Defaults to `true` for when using an image Dockerfile and `false` when referencing a Docker Compose file. | | `features` (currently in preview) | object | An object of dev container 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | -| `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose).

⚠️ Does not apply to Codespaces. | +| `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose). | ## Tool-specific properties @@ -92,7 +92,7 @@ The `portsAttributes` and `otherPortsAttributes` properties allow you to map def | Property | Type | Description | |----------|------|-------------| | `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 Codespaces 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. | +| `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 `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`. | @@ -133,7 +133,7 @@ Variables can be referenced in certain string values in `devcontainer.json` in t | 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. To 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}" }`

⚠️ For Codespaces, 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 this case, called `VARIABLE_NAME`). Unset variables are left blank. To 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}" }`

⚠️ For a cloud service, the host is in the cloud rather than your local machine.| | `${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" }` | | `${localWorkspaceFolder}` | Any | Path of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | | `${containerWorkspaceFolder}` | Any | The path that the workspaces files can be found in the container. | From b4477deea7108c1742731a5efa8217b23663e4b5 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 18 Feb 2022 09:03:26 -0800 Subject: [PATCH 14/28] Update supporting doc --- docs/supporting-tools.md | 45 ++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index bb118a6f..02e64c4c 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -4,11 +4,11 @@ A `devcontainer.json` file in your project tells tools and services that support This document outlines tools and services that currently support this format. -## Visual Studio Code Remote - Containers +While most [dev container properties](devcontainerjson-reference.md) apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. -The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. +## devcontainer CLI -> **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. +Given the growing number of use cases for dev containers, there is a companion [devcontainer command line interface](https://code.visualstudio.com/docs/remote/devcontainer-cli) (CLI) that can be used independent of the Remote - Containers extension or GitHub Codespaces. ## GitHub Codespaces @@ -16,34 +16,35 @@ A [codespace](https://docs.github.com/en/codespaces/overview) is a development e > **Tip:** If you've already built a container and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. -## devcontainer CLI +### Product specific limitations -Given the growing number of use cases for dev containers, there is a companion [devcontainer command line interface](https://code.visualstudio.com/docs/remote/devcontainer-cli) (CLI) that can be used independent of the Remote - Containers extension or GitHub Codespaces. +Some properties may apply differently to Codespaces. Please note that Codespaces supports [VS Code properties](#visual-studio-code-remote---containers). -## Schema +| Property or variable | Type | Description | +|----------|---------|----------------------| +| `mounts` | array | Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| +| `workspaceMount` | string | Not yet supported in Codespaces. | +| `workspaceFolder` | string | Not yet supported in Codespaces. | +| `forwardPorts` | array | Codespaces does not yet support the `"host:port"` variation of this property. | +| `portsAttributes` | object | Codespaces does not yet support the `"host:port"` variation of this property.| +| `shutdownAction` | enum | Does not apply to Codespaces. | +| `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| -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). +## Visual Studio Code Remote - Containers + +The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. There is more information in the Remote - Containers [documentation](https://code.visualstudio.com/docs/remote/containers). + +> **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. -## Tool-specific properties -While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. +### Product specific properties -### VS Code +Some properties are specific to VS Code. Please note that Codespaces supports the VS Code properties. | Property | Type | Description | |----------|------|-------------| | `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 `{}`. | -### GitHub Codespaces - -Certain properties work differently in Codespaces than other tools. +## Schema -| Property or variable | Type | Description | -|----------|---------|----------------------| -| `mounts` | array | Codespaces ignores "bind" mounts with the exception of the Docker socket. Volume mounts are still allowed.| -| `workspaceMount` | string | Not yet supported in Codespaces. | -| `workspaceFolder` | string | Not yet supported in Codespaces. | -| `forwardPorts` | array | Codespaces does not yet support the `"host:port"` variation of this property. | -| `portsAttributes` | object | Codespaces does not yet support the `"host:port"` variation of this property.| -| `shutdownAction` | enum | Does not apply to Codespaces. | -| `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| \ No newline at end of file +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). \ No newline at end of file From a10c2bcd10e62a9b29520bec358d1176e76fb041 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 18 Feb 2022 09:07:51 -0800 Subject: [PATCH 15/28] Add/move limitations --- docs/devcontainerjson-reference.md | 8 ++++---- docs/supporting-tools.md | 11 +++++++++++ 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/devcontainerjson-reference.md b/docs/devcontainerjson-reference.md index ba23e3ab..b51a7a79 100644 --- a/docs/devcontainerjson-reference.md +++ b/docs/devcontainerjson-reference.md @@ -20,8 +20,8 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | | `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]` | -| `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"`

⚠️ Not yet supported when using Clone Repository in Container Volume. | -| `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.

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `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"` | +| `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" ]` . | #### Publishing vs forwarding ports @@ -135,7 +135,7 @@ Variables can be referenced in certain string values in `devcontainer.json` in t |----------|---------|----------------------| | `${localEnv:VARIABLE_NAME}` | Any | Value of an environment variable on the **host machine** (in this case, called `VARIABLE_NAME`). Unset variables are left blank. To 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}" }`

⚠️ For a cloud service, the host is in the cloud rather than your local machine.| | `${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" }` | -| `${localWorkspaceFolder}` | Any | Path of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `${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`).

⚠️ Not yet supported when using Clone Repository in Container Volume. | +| `${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. | \ No newline at end of file diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index 02e64c4c..33efb4b5 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -45,6 +45,17 @@ Some properties are specific to VS Code. Please note that Codespaces supports th | `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 `{}`. | +### Product specific limitations + +Some properties may also have certain limitations in the Remote - Containers extension. + +| Property or variable | Type | Description | +|----------|------|-------------| +| `workspaceMount` | string | Not yet supported when using Clone Repository in Container Volume. | +| `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. | + ## 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). \ No newline at end of file From a14352bd90e011d490202707035e2c567d8adf72 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 22 Feb 2022 12:45:33 -0800 Subject: [PATCH 16/28] Wording --- docs/supporting-tools.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index 33efb4b5..36f28d1e 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -1,10 +1,8 @@ # Supporting tools and services -A `devcontainer.json` file in your project tells tools and services that support the dev container spec how to access (or create) a **development 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. -This document outlines tools and services that currently support this format. - -While most [dev container properties](devcontainerjson-reference.md) apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. +While most [dev container properties](devcontainerjson-reference.md) apply to any supporting tool or service, a few are specific to certain tools, which are outlined below. ## devcontainer CLI @@ -14,7 +12,7 @@ Given the growing number of use cases for dev containers, there is a companion [ A [codespace](https://docs.github.com/en/codespaces/overview) is a development environment that's hosted in the cloud. Codespaces run on a variety of VM-based compute options hosted by GitHub.com, which you can configure from 2 core machines up to 32 core machines. You can connect to your codespaces from the browser or locally using Visual Studio Code. -> **Tip:** If you've already built a container and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. +> **Tip:** If you've already built a codespace and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. ### Product specific limitations From 07d646567801446903948910efc180515f3e5aa7 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 23 Feb 2022 11:44:38 -0800 Subject: [PATCH 17/28] Update CLI --- docs/supporting-tools.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/supporting-tools.md b/docs/supporting-tools.md index 36f28d1e..1573f992 100644 --- a/docs/supporting-tools.md +++ b/docs/supporting-tools.md @@ -4,9 +4,9 @@ This page outlines tools and services that currently support the development con While most [dev container properties](devcontainerjson-reference.md) apply to any supporting tool or service, a few are specific to certain tools, which are outlined below. -## devcontainer CLI +## Dev container CLI -Given the growing number of use cases for dev containers, there is a companion [devcontainer command line interface](https://code.visualstudio.com/docs/remote/devcontainer-cli) (CLI) that can be used independent of the Remote - Containers extension or GitHub Codespaces. +Given the growing number of use cases for dev containers, there is a companion dev container command line interface (CLI) that can be used independent of specific tools or editors. The publishing of this CLI is being discussed in an [issue](https://github.com/microsoft/dev-container-spec/issues/9). ## GitHub Codespaces @@ -54,6 +54,10 @@ Some properties may also have certain limitations in the Remote - Containers ext | `${localWorkspaceFolder}` | Any | Not yet supported when using Clone Repository in Container Volume. | | `${localWorkspaceFolderBasename}` | Any | Not yet supported when using Clone Repository in Container Volume. | +## Remote - Containers CLI + +There is a Remote - Containers [`devcontainer` CLI](https://code.visualstudio.com/docs/remote/devcontainer-cli) which may be installed within Remote - Containers or through the command line. + ## 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). \ No newline at end of file From b4833e9e9ccc578f10795b92b5d2eb6395046818 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 23 Feb 2022 11:45:52 -0800 Subject: [PATCH 18/28] Update folder structure --- docs/{ => specs/schemas}/devcontainerjson-reference.md | 0 docs/{ => specs/schemas}/supporting-tools.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/{ => specs/schemas}/devcontainerjson-reference.md (100%) rename docs/{ => specs/schemas}/supporting-tools.md (100%) diff --git a/docs/devcontainerjson-reference.md b/docs/specs/schemas/devcontainerjson-reference.md similarity index 100% rename from docs/devcontainerjson-reference.md rename to docs/specs/schemas/devcontainerjson-reference.md diff --git a/docs/supporting-tools.md b/docs/specs/schemas/supporting-tools.md similarity index 100% rename from docs/supporting-tools.md rename to docs/specs/schemas/supporting-tools.md From ba41a4bbac172e9747a89ee75fa1813b3d5dda89 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 23 Feb 2022 11:47:30 -0800 Subject: [PATCH 19/28] Update links --- docs/specs/schemas/devcontainerjson-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/schemas/devcontainerjson-reference.md b/docs/specs/schemas/devcontainerjson-reference.md index b51a7a79..ae0393f9 100644 --- a/docs/specs/schemas/devcontainerjson-reference.md +++ b/docs/specs/schemas/devcontainerjson-reference.md @@ -1,6 +1,6 @@ # devcontainer.json reference -A `devcontainer.json` file in your project tells [tools and services that support the dev container spec](/docs/supporting-tools.md) how to access (or create) a **development container** with a well-defined tool and runtime stack. +A `devcontainer.json` file in your project tells [tools and services that support the dev container spec](supporting-tools.md) how to access (or create) a **development container** with a well-defined tool and runtime stack. ## Scenario specific properties @@ -55,7 +55,7 @@ Docker has the concept of "publishing" ports when the container is created. Publ ## Tool-specific properties -While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. You may explore this in the [supporting tools and services document](/docs/supporting-tools.md/#tool-specific-properties). +While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. You may explore this in the [supporting tools and services document](supporting-tools.md). ## Lifecycle scripts From 4c87154197b833adc75b55d3d0049a80482f17db Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 23 Feb 2022 11:54:14 -0800 Subject: [PATCH 20/28] Folders --- docs/specs/{schemas => }/devcontainerjson-reference.md | 0 docs/specs/{schemas => }/supporting-tools.md | 0 2 files changed, 0 insertions(+), 0 deletions(-) rename docs/specs/{schemas => }/devcontainerjson-reference.md (100%) rename docs/specs/{schemas => }/supporting-tools.md (100%) diff --git a/docs/specs/schemas/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md similarity index 100% rename from docs/specs/schemas/devcontainerjson-reference.md rename to docs/specs/devcontainerjson-reference.md diff --git a/docs/specs/schemas/supporting-tools.md b/docs/specs/supporting-tools.md similarity index 100% rename from docs/specs/schemas/supporting-tools.md rename to docs/specs/supporting-tools.md From fc88a5ea533fdfb59b7ebc6cbb455f4d501d454e Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Wed, 23 Feb 2022 14:55:34 -0800 Subject: [PATCH 21/28] Learn more links --- docs/specs/devcontainerjson-reference.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index ae0393f9..2bc27f7c 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -15,8 +15,8 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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.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-devcontainerjson-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). | +| `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`.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | +| `appPort` | integer,
string,
array | In most cases, we recommend using the new [forwardPorts property](#general-devcontainerjson-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. | | `containerEnv` | object | A set of name-value pairs that sets or overrides environment variables for the container. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. For example:
`"containerEnv": { "MY_VARIABLE": "${localEnv:MY_VARIABLE}" }`
Requires the container be recreated / rebuilt to change. If you want to reference an existing container variable while setting this one (like updating the `PATH`), use `remoteEnv` instead. | | `containerUser` | string | Overrides the user for all operations run as inside the container. Defaults to either `root` or the last `USER` instruction in the related Dockerfile used to create the image.
On Linux, the specified container user's UID/GID will be updated to match the local user's UID/GID to avoid permission problems with bind mounts (unless disabled using `updateRemoteUserUID`).
Requires the container be recreated / rebuilt for updates to take effect. If you want any connected tools or related processes to use a different user than the one for the container, see `remoteUser`. | | `mounts` | array | An array of additional mount points to add to the container when created. 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=${localWorkspaceFolder}/app-scripts,target=/usr/local/share/app-scripts,type=bind,consistency=cached"]` | @@ -32,7 +32,7 @@ Docker has the concept of "publishing" ports when the container is created. Publ | Property | Type | Description | |----------|------|-------------| -| `dockerComposeFile` | string,
array | **Required** when [using Docker Compose](https://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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://code.visualstudio.com/docs/remote/create-dev-container#_extend-your-docker-compose-file-for-development). 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. | +| `dockerComposeFile` | string,
array | **Required** when [using Docker Compose](https://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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://code.visualstudio.com/docs/remote/create-dev-container#_extend-your-docker-compose-file-for-development). 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://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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 `"/"`. | @@ -63,12 +63,12 @@ When creating or working with a dev container, you may need different commands t | Property | Type | Description | |----------|------|-------------| -| `initializeCommand` | string,
array | 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. | -| `onCreateCommand` | string,
array | 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. | -| `updateContentCommand` | string,
array | 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. | -| `postCreateCommand` | string,
array | 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. | -| `postStartCommand` | string,
array | A command to run each time the container is successfully started. | -| `postAttachCommand` | string,
array | A command to run each time a tool has successfully attached to the container. | +| `initializeCommand` | string,
array | 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 properties. | +| `onCreateCommand` | string,
array | 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 properties. | +| `updateContentCommand` | string,
array | 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 properties. | +| `postCreateCommand` | string,
array | 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 properties. | +| `postStartCommand` | string,
array | 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 properties. | +| `postAttachCommand` | string,
array | 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 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. | 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` From 089c45f82d07af7240e57166835f94962f6f1c3e Mon Sep 17 00:00:00 2001 From: Brigit Murtaugh Date: Fri, 25 Feb 2022 11:10:21 -0800 Subject: [PATCH 22/28] Update CLI description --- docs/specs/supporting-tools.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 1573f992..46d5ee2c 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -6,7 +6,9 @@ While most [dev container properties](devcontainerjson-reference.md) apply to an ## Dev container CLI -Given the growing number of use cases for dev containers, there is a companion dev container command line interface (CLI) that can be used independent of specific tools or editors. The publishing of this CLI is being discussed in an [issue](https://github.com/microsoft/dev-container-spec/issues/9). +There will be a dev container command line interface (CLI) that can take a `devcontainer.json` and create and configure a dev container from it. + +The publishing of this CLI is being discussed in an [issue](https://github.com/microsoft/dev-container-spec/issues/9). ## GitHub Codespaces @@ -60,4 +62,4 @@ There is a Remote - Containers [`devcontainer` CLI](https://code.visualstudio.co ## 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). \ No newline at end of file +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). From bf9af79c7e111b2f016d840b47898c6a3d42b42d Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Thu, 3 Mar 2022 10:08:43 -0800 Subject: [PATCH 23/28] Moved ports section --- docs/specs/devcontainerjson-reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index 2bc27f7c..2dd2e709 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -24,10 +24,6 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `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" ]` . | -#### Publishing vs forwarding ports - -Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application. - ### Docker Compose specific properties | Property | Type | Description | @@ -53,6 +49,10 @@ Docker has the concept of "publishing" ports when the container is created. Publ | `features` (currently in preview) | object | An object of dev container 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | | `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose). | +## Publishing vs forwarding ports + +Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application. + ## Tool-specific properties While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. You may explore this in the [supporting tools and services document](supporting-tools.md). From 10e79d25ca8400c51f330f6591b062332b341ccb Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Thu, 3 Mar 2022 10:09:59 -0800 Subject: [PATCH 24/28] Move ports --- docs/specs/devcontainerjson-reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index 2dd2e709..89634432 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -49,10 +49,6 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | `features` (currently in preview) | object | An object of dev container 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": {"github-cli": "latest"}`

⚠️ Currently in preview. | | `shutdownAction` | enum | Indicates whether `devcontainer.json` supporting tools should stop the containers when the related tool window is closed / shut down.
Values are `none`, `stopContainer` (default for image or Dockerfile), and `stopCompose` (default for Docker Compose). | -## Publishing vs forwarding ports - -Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application. - ## Tool-specific properties While most properties apply to any `devcontainer.json` supporting tool or service, a few are specific to certain tools. You may explore this in the [supporting tools and services document](supporting-tools.md). @@ -97,6 +93,10 @@ The `portsAttributes` and `otherPortsAttributes` properties allow you to map def | `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`. | +## Publishing vs forwarding ports + +Docker has the concept of "publishing" ports when the container is created. Published ports behave very much like ports you make available to your local network. If your application only accepts calls from `localhost`, it will reject connections from published ports just as your local machine would for network calls. Forwarded ports, on the other hand, actually look like `localhost` to the application. + ## Formatting string vs. array properties The format of certain properties will vary depending on the involvement of a shell. From 77378610d4039b11c2abb23c31f50a3cc83d39c8 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Thu, 3 Mar 2022 10:12:19 -0800 Subject: [PATCH 25/28] Update Codespaces --- docs/specs/supporting-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 46d5ee2c..6e332c75 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -18,7 +18,7 @@ A [codespace](https://docs.github.com/en/codespaces/overview) is a development e ### Product specific limitations -Some properties may apply differently to Codespaces. Please note that Codespaces supports [VS Code properties](#visual-studio-code-remote---containers). +Some properties may apply differently to Codespaces. Please note that Codespaces, both through the Codespaces web editor and VS Code client, and supports [VS Code properties](#visual-studio-code-remote---containers). | Property or variable | Type | Description | |----------|---------|----------------------| From e5446a3054270bf722c2bb69df23bd65ce48b8aa Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Thu, 3 Mar 2022 15:47:52 -0800 Subject: [PATCH 26/28] Codespaces content --- docs/specs/supporting-tools.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 6e332c75..6871a609 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -16,9 +16,12 @@ A [codespace](https://docs.github.com/en/codespaces/overview) is a development e > **Tip:** If you've already built a codespace and connected to it, be sure to run **Codespaces: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make. +### Product specific properties +GitHub Codespaces works with a growing number of tools and, where applicable, their `devcontainer.json` properties. For example, connecting the Codespaces web editor or VS Code enables the use of [VS Code properties](#visual-studio-code-remote---containers). + ### Product specific limitations -Some properties may apply differently to Codespaces. Please note that Codespaces, both through the Codespaces web editor and VS Code client, and supports [VS Code properties](#visual-studio-code-remote---containers). +Some properties may apply differently to Codespaces. | Property or variable | Type | Description | |----------|---------|----------------------| From f58016d9275e14a127d8615ca3e45c0b10d494d8 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Tue, 8 Mar 2022 15:28:09 -0800 Subject: [PATCH 27/28] Update docs link --- docs/specs/devcontainerjson-reference.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index 89634432..9b54d3d2 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -10,7 +10,7 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | Property | Type | Description | |----------|------|-------------| -| `image` | string | **Required** when [using an image](https://code.visualstudio.com/docs/remote/create-dev-container#_using-an-image-or-dockerfile). 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. | +| `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}" } }` | @@ -28,8 +28,8 @@ The focus of `devcontainer.json` is to describe how to enrich a container for th | Property | Type | Description | |----------|------|-------------| -| `dockerComposeFile` | string,
array | **Required** when [using Docker Compose](https://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). 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://code.visualstudio.com/docs/remote/create-dev-container#_extend-your-docker-compose-file-for-development). 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://code.visualstudio.com/docs/remote/create-dev-container#_use-a-dockerfile). The name of the service `devcontainer.json` supporting services / tools should connect to once running. | +| `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. | | `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 `"/"`. | From f631939f4a7ee8639aac9414b77eb423a96f24f8 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Mon, 14 Mar 2022 15:26:17 -0700 Subject: [PATCH 28/28] Just "container" --- docs/specs/supporting-tools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 6871a609..524c92d9 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -35,7 +35,7 @@ Some properties may apply differently to Codespaces. ## Visual Studio Code Remote - Containers -The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a [Docker container](https://docker.com) as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. There is more information in the Remote - Containers [documentation](https://code.visualstudio.com/docs/remote/containers). +The [**Visual Studio Code Remote - Containers** extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) lets you use a container as a full-featured development environment. It allows you to open any folder inside (or mounted into) a container and take advantage of Visual Studio Code's full feature set. There is more information in the Remote - Containers [documentation](https://code.visualstudio.com/docs/remote/containers). > **Tip:** If you've already built a container and connected to it, be sure to run **Remote-Containers: Rebuild Container** from the Command Palette (`kbstyle(F1)`) to pick up any changes you make.