From f1d171e4953950215fad12a636bb83326b5afe32 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Thu, 5 May 2022 00:11:47 +0000 Subject: [PATCH 01/10] Initial version --- docs/specs/devcontainer-reference.md | 199 +++++++++++++++++++++++ docs/specs/devcontainerjson-reference.md | 146 +++++++++++++++++ docs/specs/supporting-tools.md | 64 ++++++++ 3 files changed, 409 insertions(+) create mode 100644 docs/specs/devcontainer-reference.md create mode 100644 docs/specs/devcontainerjson-reference.md create mode 100644 docs/specs/supporting-tools.md diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md new file mode 100644 index 00000000..949ff792 --- /dev/null +++ b/docs/specs/devcontainer-reference.md @@ -0,0 +1,199 @@ +# Devcontainers specificaction + +The purpose of this specification is to define a file format and accompanying tools required to generate repeatable **development containers**. + +The focus of the devcontainer specification 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 lifecycle. 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. + +A **development container** is defined as the set of logically related containers (as defined by the underlying orchestrator format) and the different lifecycle events that operate on them for this environments to be useful for development. Additionally, tools that want to implement this specification should provide a set of features/commands that give more flexibility to users and allow this **development containers** to scale to large development groups. Even though a **development container** can consist of multiple environments, most operations deal with the **main** container defined in `devcontainer.json`. + +# Application Model + +**Development containers** allow one to define a repeatable development environment for a team that is related to the execution environment of the application itself. In a way a **development container** can be a superset of all the required tools for the application being developed adding any tools required for compiling, debugging, diagnosing and testing said application. + +In this intent a **development container** is composed of a deterministic definition on a `devcontainer.json` file that creates containers under the control of the user. + +The `devcontainer.json` specification contains diferent configuration options related to the underlying orchestrator format and its not expected that all implementations support all of them. At the same time this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. + +The application model consists of actions defined at different points in the lifecycle of the **development container** that allow users to control all aspects of how they are created and managed. Similarly this specification allows users to have other mechanisms to generate the different images required by their application and just reference them in `devcontainer.json`. + +The **development containers** format is primarily tasked with the setup of a container or group of containers required for an application while focusing the configuration in the **main** container that the developer is interested in. + +To create a **development containers** configuration a user would go through the following: + +- Analyze the current requirements of the application. + - Separate requirements to run the application from the ones needed to develop it. (f.e. SDKs, compilation tools, source control, etc.) +- Select a type of [configuration](#configuration-options). +- Define at least the required parameters of each configuration. +- Create a `devcontainer.json` file and set it in the application code. + +Additionally the user could think of further configuration options like: + +- Environment variables required. +- Tokens and security concerns. +- User permisions. +- Container run configuration. [See `overrideCommand`](devcontainerjson-reference.md#general-devcontainerjson-properties). + +In all cases paths are relative to the location of `devcontainer.json`. + +A lot of the parameters defined in `devcontainer.json` are for environment specific tools to implement depending on their needs, for example, `portsAttributes`, `remoteUser`, `remoteEnv`, etc. + +# Configuration options + +## Image based + +Image based configurations only reference an image that should be reachable and downloadable through `docker pull` commands. Logins and tokens required for this operations are assumed to be already taken care of. The only required parameter is `image` . The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). + + +## Dockerfile based + +This configurations are defined as using a `Dockerfile` to define the starting point of the **development containers**. As with image based configurations, it is assumed that any base images are already reachable by **docker** when performing a `docker build` command.The only required parameter in this case is the relative reference to the `Dockerfile` in `build.dockerfile`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). + +There are multiple properties that allow users to control `docker build` works: + +- `build.context` +- `build.args` +- `build.target`, +- `build.cacheFrom` + +## Docker Compose based + +Docker compose configurations utilize `docker-compose` to create and manage a set of containers required for an application. As with the other configurations, any images required for this operation are assumed to be reachable. The required parameters are: + +- `build.dockerComposeFile` the reference to the docker-compose file(s) to be used. +- `service` this tag declares the **main** container that will be used for all other operations. Tools are assumed to also use this parameter to connect to the **development container** although they can provide facilities to connect to the other containers as required by the user. + +It is important to remark that due to how `docker-compose` works a lot of the properties that apply to **image** and **dockerfile** configurations cant be set by the application and thus must be setup manually by the user using the `docker-compose` format itself. + +# Other options + +In addition to the configuration options explained above there are other settings that apply when creating the **development containers** to facilitate their use by developers. This properties mostly apply to **image** and **dockerfile** based configurations. + +The main ones are: + +## Environment Variables + +Environment variables can be set in containers at creation time, to override existing ones, or just to be used when a supporting tool connects to the environment. + +## Mounts + +Mounts allow containers to have access to the underlying machine, share data between containers and to persist information between **development containers**. + +It is important to note that this mounts are from the underlying compute environment and thus in cloud enviroments might not have access to the same data as a local machine. + +## Users + +Users control the permisions of applications executed in the containers, allowing the developer to control them. + +# Lifecycle + +A development environment goes through different lifecycle events during their use in the outer and inner loop of development. + +- Configuration Validation +- Environment Creation. +- Environment Stop. +- Environment Resume. +- Environment Connection. + +## Configuration validation + +This section consists of actions required to validate the `devcontainer.json` configuration is valid and does not contain values that conflict with each other. + +The tasks executed when validating the configuration are: + +- Validate command line parameters are consistent: + - `workspace-folder` is required since it defines where the `devcontainer.json` file is located. +- Validate access to the `workspace-folder`. Identify that a `devcontainer.json` file is located in the defined locations. [see here](devcontainerjson-reference.md) +- Validate that additional parameters have the correct format. +- Validate that `devcontainer.json` contains all parameters required for the selected configuration type. + +## Environment Creation + +### Initialization + +During this step the following is executed: +- Validate access to the container orchestrator specified by the configuration. +- Execution of `initializeCommand`. + +### Image creation + +The first part of an environment creation is generating the final image(s) that the **development containers** are going to use. This step is orchestrator dependent and can consist of just pulling a docker image, running docker build, or docker-compose build. Additionally this step is useful by its own since it permits the creation of intermediate images that can be uploaded and used by other users and thus cut down on creation time. It is encouraged that tools implementing this specification give access to a command that just executes this step. + +This step executes the following: + +- [Configuration Validation](#configuration-validation) +- Pull/build/execute of the defined container orchestration format to create images. +- Validate the result of this operations. + +### Container creation. + +After image creation containers are created based on that image and setup. + +This step executes the following: + +- Create the container with the specified properties. +- Validate the container(s) were created successfully. + +### Post container creation. + +- At the end of the container creation step, a set of commands are executed inside the **main** container `on-create-command`, `update-content-command` and `post-create-command`. This set of commands are executed in sequence on a container the first time its created and depending on the creation parameters received, [see here](devcontainerjson-reference.md#lifecycle-scripts) to learn more. By default `post-create-command` is executed in the background after reporting the successful creation of the development environment, this behavior depends on the `wait-for` property defined. + +## Environment stop. + +Stops all containers in the environment. The intention of this step is to ensure all containers are stopped correctly to ensure no data is lost. + +## Environment Restart + +After an environment has been stopped the containers are restarted according to the orchestrator defined. Additionally `post-start-command` is executed in the **main** container. + +## Environment Connection + +`devcontainer.json` has `post-attach-command` defined that should be executed after any tools attach to the container. These tools should call for the execution of this command. + +# Tool features + +Tools implementing this specification (like the reference implementation) are encouraged to support at least the following features: + +## Identification + +Tools implementing this specificaction should have a way to track what images and containers belong to a particular **development container** allowing the user to keep multiple on an environment and select which one to operate on. + +## Definition merge and validation +`read-configuration` + +This command should execute all validation tasks on the `devcontainer.json` format as defined [here](devcontainerjson-reference.md). + +## Image build +`build` + +Executes all steps of the lifecycle up to the build step. This allows users to take this images and publish them. + +## Environment creation +`up` + +Executes all steps required to obtain a working **development container**, executing tasks in the background as defined [here](#post-container-creation). + +## Stop +`stop` + +Executes a safe stop of all containers related to the **development container**. + +## Stop and Delete +`down` + +Executes stop and in addition deletes all containers related to the **development containers**. + +## Execute user commands +`run-user-commands` + +Runs the asynchronous commands on an environment according to paramenters received. It should be possible for the user to control which ones run. Namely: + +- `onCreate` +- `updateContent` +- `postCreateCommand` +- `postAttachCommand` +- `postStartCommand`. + +## Execute manual commands +`exec` + +Executes commands inside the **main** container of a development environment specified to the user. \ No newline at end of file diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md new file mode 100644 index 00000000..69114d38 --- /dev/null +++ b/docs/specs/devcontainerjson-reference.md @@ -0,0 +1,146 @@ +# devcontainer.json reference + +The `devcontainer.json` file contains the definition of the **development environment**. This file in your project tells [tools and services that support the dev container spec](supporting-tools.md) how to access (or create) a **development environment** with a well-defined tool and runtime stack. + +The default locations of `devcontainer.json` file are relative to the `workspace-folder` and are as follows: +- under `./.devcontainer` folder +- Directly under the `workspace-folder` as `.devcontainer.json` + +## 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). 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). | +| `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` (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). | + +## Image or Dockerfile specific properties + +| Property | Type | Description | +|----------|------|-------------| +| `image` | string | **Required** when using an image. The name of an image in a container registry ([DockerHub](https://hub.docker.com), [GitHub Container Registry](https://docs.github.com/packages/guides/about-github-container-registry), [Azure Container Registry](https://azure.microsoft.com/services/container-registry/)) that `devcontainer.json` supporting services / tools should use to create the dev container. | +| `build.dockerfile` | string |**Required** when using a Dockerfile. The location of a [Dockerfile](https://docs.docker.com/engine/reference/builder/) that defines the contents of the container. The path is relative to the `devcontainer.json` file. | +| `build.context` | string | Path that the Docker build should be run from relative to `devcontainer.json`. For example, a value of `".."` would allow you to reference content in sibling directories. Defaults to `"."`. | +| `build.args` | Object | A set of name-value pairs containing [Docker image build arguments](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) that should be passed when building a Dockerfile. Environment and [pre-defined variables](#variables-in-devcontainerjson) may be referenced in the values. Defaults to not set. For example: `"build": { "args": { "MYARG": "MYVALUE", "MYARGFROMENVVAR": "${localEnv:VARIABLE_NAME}" } }` | +| `build.target` | string | A string that specifies a [Docker image build target](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) that should be passed when building a Dockerfile. Defaults to not set. For example: `"build": { "target": "development" }` | +| `build.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"]` | +| `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" ]` . | + +### Docker Compose specific properties + +| Property | Type | Description | +|----------|------|-------------| +| `dockerComposeFile` | string,
array | **Required** when [using Docker Compose](https://docs.docker.com/compose/). Path or an ordered list of paths to Docker Compose files relative to the `devcontainer.json` file. Using an array is useful [when extending your Docker Compose configuration](https://docs.docker.com/compose/extends/#multiple-compose-files). The order of the array matters since the contents of later files can override values set in previous ones.
The default `.env` file is picked up from the root of the project, but you can use `env_file` in your Docker Compose file to specify an alternate location.
Note that the array syntax will execute the command without a shell. You can [learn more](#formatting-string-vs-array-properties) about formatting string vs array properties. | +| `service` | string | **Required** when [using Docker Compose](https://docs.docker.com/compose/). The name of the service `devcontainer.json` supporting services / tools should connect to once running. | +| `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 `"/"`. | + +## 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 + +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 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` + +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 can use these properties to automatically default to the best compute option available, while in other cases, you will be presented with a warning if the requirements are not met. + +| Property | Type | Description | +|----------|------|-------------| +| `hostRequirements.cpus` | integer | Indicates the minimum required number of CPUs / virtual CPUs / cores. For example: `"hostRequirements": {"cpus": 2}` | +| `hostRequirements.memory` | string | A string indicating minimum memory requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"memory": "4gb"}` | +| `hostRequirements.storage` | string | A string indicating minimum storage requirements with a `tb`, `gb`, `mb`, or `kb` suffix. For example, `"hostRequirements": {"storage": "32gb"}` | + +## 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 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`. | + +## 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 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`). | +| `${containerWorkspaceFolder}` | Any | The path that the workspaces files can be found in the container. | +| `${localWorkspaceFolderBasename}` | Any | Name of the local folder that was opened in the `devcontainer.json` supporting service / tool (that contains `.devcontainer/devcontainer.json`). | +| `${containerWorkspaceFolderBasename}` | Any | Name of the folder where the workspace files can be found in the container. | + +## 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). + + +## 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. \ No newline at end of file diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md new file mode 100644 index 00000000..6d3dcc54 --- /dev/null +++ b/docs/specs/supporting-tools.md @@ -0,0 +1,64 @@ +# Supporting tools and services + +This page outlines tools and services that currently support the development container specification, including the `devcontainer.json` format. A `devcontainer.json` file in your project tells tools and services that support the dev container spec how to access (or create) a dev container with a well-defined tool and runtime stack. + +While most [dev container properties](devcontainerjson-reference.md) apply to any supporting tool or service, a few are specific to certain tools, which are outlined below. + +## Dev container CLI + +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 + +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 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. + +| 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.| + +## 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 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. + +### Product specific properties + +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 `{}`. | + +### 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. | + +## 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. \ No newline at end of file From f4a5a7193b5b8fca85b7fdfec1a3a1ba4d123c9c Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Mon, 16 May 2022 22:26:43 +0000 Subject: [PATCH 02/10] Comments --- docs/specs/devcontainer-reference.md | 145 +++++++++------------------ 1 file changed, 45 insertions(+), 100 deletions(-) diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md index 949ff792..38989b07 100644 --- a/docs/specs/devcontainer-reference.md +++ b/docs/specs/devcontainer-reference.md @@ -1,52 +1,40 @@ -# Devcontainers specificaction +# Dev container specification -The purpose of this specification is to define a file format and accompanying tools required to generate repeatable **development containers**. +The purpose of the **development container** specification is to provide a way to enrich containers with the needed content and metadata necessary to enable development inside them. This container **environments** should be easy to use, create and easy to recreate. -The focus of the devcontainer specification 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 lifecycle. 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. +A **development container** is a container that a user can use to develop an application inside of. Additionally, tools that want to implement this specification should provide a set of features/commands that give more flexibility to users and allow **development containers** to scale to large development groups. -A **development container** is defined as the set of logically related containers (as defined by the underlying orchestrator format) and the different lifecycle events that operate on them for this environments to be useful for development. Additionally, tools that want to implement this specification should provide a set of features/commands that give more flexibility to users and allow this **development containers** to scale to large development groups. Even though a **development container** can consist of multiple environments, most operations deal with the **main** container defined in `devcontainer.json`. +An **environment** is defined as a logical instance of one or more **development containers** along with any needed side-car containers based on one set of metadata that can be managed as a single unit. Users can create multiple **environments** from the same configuration metadata for different purposes. -# Application Model +Historically dev containers have been used to enable a development workflow used either locally or on the cloud and have been focused on using **Docker** or **docker-compose**. The intent of this specification and related tools is to expand the reach of **development containers**, allow the usage of containers by themselves or different orchestration technologies, and allow any tool to manage and create them. -**Development containers** allow one to define a repeatable development environment for a team that is related to the execution environment of the application itself. In a way a **development container** can be a superset of all the required tools for the application being developed adding any tools required for compiling, debugging, diagnosing and testing said application. +The focus of the dev container specification is to describe how to enrich a container for the purposes of development rather than acting as a multi-container orchestrator format. Container orchestrator formats can be referenced, when needed, to manage multiple containers and the **Development container** lifecycle. 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. -In this intent a **development container** is composed of a deterministic definition on a `devcontainer.json` file that creates containers under the control of the user. +# Metadata -The `devcontainer.json` specification contains diferent configuration options related to the underlying orchestrator format and its not expected that all implementations support all of them. At the same time this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. +**Development containers** allow one to define a repeatable development environment for a user or team of developers that includes the execution environment the application needs. A development container defines an environment in which you develop your application before you are ready to deploy. While deployment and development containers may resemble one another, you may not want to include tools in a deployment image that you use during development. -The application model consists of actions defined at different points in the lifecycle of the **development container** that allow users to control all aspects of how they are created and managed. Similarly this specification allows users to have other mechanisms to generate the different images required by their application and just reference them in `devcontainer.json`. +A **development container** is composed of a definition (e.g. contained in a `devcontainer.json` file) that deterministically creates containers under the control of the user. -The **development containers** format is primarily tasked with the setup of a container or group of containers required for an application while focusing the configuration in the **main** container that the developer is interested in. +## `devcontainer.json` -To create a **development containers** configuration a user would go through the following: +The current metadata schema for **development containers** is contained in a `devcontainer.json` file. -- Analyze the current requirements of the application. - - Separate requirements to run the application from the ones needed to develop it. (f.e. SDKs, compilation tools, source control, etc.) -- Select a type of [configuration](#configuration-options). -- Define at least the required parameters of each configuration. -- Create a `devcontainer.json` file and set it in the application code. +The `devcontainer.json` specification contains different configuration options related to the underlying orchestrator format. At the same time this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. -Additionally the user could think of further configuration options like: - -- Environment variables required. -- Tokens and security concerns. -- User permisions. -- Container run configuration. [See `overrideCommand`](devcontainerjson-reference.md#general-devcontainerjson-properties). - -In all cases paths are relative to the location of `devcontainer.json`. - -A lot of the parameters defined in `devcontainer.json` are for environment specific tools to implement depending on their needs, for example, `portsAttributes`, `remoteUser`, `remoteEnv`, etc. # Configuration options +**Development containers** currently supports multiple ways to specify the containers that create an environment. The following section describes the differences between them. + ## Image based -Image based configurations only reference an image that should be reachable and downloadable through `docker pull` commands. Logins and tokens required for this operations are assumed to be already taken care of. The only required parameter is `image` . The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). +Image based configurations only reference an image that should be reachable and downloadable through `docker pull` commands. Logins and tokens required for these operations are execution environment specific.. The only required parameter is `image` . The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). ## Dockerfile based -This configurations are defined as using a `Dockerfile` to define the starting point of the **development containers**. As with image based configurations, it is assumed that any base images are already reachable by **docker** when performing a `docker build` command.The only required parameter in this case is the relative reference to the `Dockerfile` in `build.dockerfile`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). +These configurations are defined as using a `Dockerfile` to define the starting point of the **development containers**. As with image based configurations, it is assumed that any base images are already reachable by **docker** when performing a `docker build` command. The only required parameter in this case is the relative reference to the `Dockerfile` in `build.dockerfile`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). There are multiple properties that allow users to control `docker build` works: @@ -62,11 +50,13 @@ Docker compose configurations utilize `docker-compose` to create and manage a s - `build.dockerComposeFile` the reference to the docker-compose file(s) to be used. - `service` this tag declares the **main** container that will be used for all other operations. Tools are assumed to also use this parameter to connect to the **development container** although they can provide facilities to connect to the other containers as required by the user. -It is important to remark that due to how `docker-compose` works a lot of the properties that apply to **image** and **dockerfile** configurations cant be set by the application and thus must be setup manually by the user using the `docker-compose` format itself. +It is important to remark that due to how `docker-compose` works a lot of the properties that apply to **image** and **dockerfile** configurations can’t be set by the application and thus must be set up manually by the user using the `docker-compose` format itself. + +-`runServices` are the set of services in the `docker-compose` configuration that should be started or stopped with the environment. # Other options -In addition to the configuration options explained above there are other settings that apply when creating the **development containers** to facilitate their use by developers. This properties mostly apply to **image** and **dockerfile** based configurations. +In addition to the configuration options explained above there are other settings that apply when creating the **development containers** to facilitate their use by developers. These properties mostly apply to **image** and **dockerfile** based configurations. The main ones are: @@ -74,40 +64,47 @@ The main ones are: Environment variables can be set in containers at creation time, to override existing ones, or just to be used when a supporting tool connects to the environment. +There are two kinds of environment variables: +Container. These variables are part of the container when it is created and are available at all points in its lifecycle. +Remote. This variables are to be set by a **development container** supporting tool as part of its environment when it runs. This variables can change during the lifetime of the container. + ## Mounts Mounts allow containers to have access to the underlying machine, share data between containers and to persist information between **development containers**. -It is important to note that this mounts are from the underlying compute environment and thus in cloud enviroments might not have access to the same data as a local machine. +It is important to note that these mounts are from the underlying compute environment and thus in cloud environments might not have access to the same data as a local machine. ## Users -Users control the permisions of applications executed in the containers, allowing the developer to control them. +Users control the permissions of applications executed in the containers, allowing the developer to control them. The specification takes into account two types of user definuitions: + +Container User. The user that will be used for all operations that run inside a container. It is used to run lifecycle commands among others. +Remote User. In case the developer wants to use different users for different purposes, the remote user is the user that connecting tools should use to execute operations inside the container. + # Lifecycle -A development environment goes through different lifecycle events during their use in the outer and inner loop of development. +A development environment goes through different lifecycle events during its use in the outer and inner loop of development. -- Configuration Validation +- Configuration Validation. - Environment Creation. - Environment Stop. - Environment Resume. - Environment Connection. -## Configuration validation +## Configuration Validation -This section consists of actions required to validate the `devcontainer.json` configuration is valid and does not contain values that conflict with each other. +This section consists of actions required to validate the `devcontainer.json` configuration and does not contain values that conflict with each other. The tasks executed when validating the configuration are: -- Validate command line parameters are consistent: - - `workspace-folder` is required since it defines where the `devcontainer.json` file is located. -- Validate access to the `workspace-folder`. Identify that a `devcontainer.json` file is located in the defined locations. [see here](devcontainerjson-reference.md) -- Validate that additional parameters have the correct format. -- Validate that `devcontainer.json` contains all parameters required for the selected configuration type. +- `workspace-folder` is required since it defines where the `devcontainer.json` file is located and identifies the configuration to be used for the environment. +- Validate access to the `workspace-folder`. +- Validate that the metadata (for example `devcontainer.json`) contains all parameters required for the selected configuration type. ## Environment Creation + ### Initialization During this step the following is executed: @@ -116,15 +113,15 @@ During this step the following is executed: ### Image creation -The first part of an environment creation is generating the final image(s) that the **development containers** are going to use. This step is orchestrator dependent and can consist of just pulling a docker image, running docker build, or docker-compose build. Additionally this step is useful by its own since it permits the creation of intermediate images that can be uploaded and used by other users and thus cut down on creation time. It is encouraged that tools implementing this specification give access to a command that just executes this step. +The first part of an environment creation is generating the final image(s) that the **development containers** are going to use. This step is orchestrator dependent and can consist of just pulling a docker image, running docker build, or docker-compose build. Additionally this step is useful on its own since it permits the creation of intermediate images that can be uploaded and used by other users and thus cut down on creation time. It is encouraged that tools implementing this specification give access to a command that just executes this step. This step executes the following: - [Configuration Validation](#configuration-validation) - Pull/build/execute of the defined container orchestration format to create images. -- Validate the result of this operations. +- Validate the result of these operations. -### Container creation. +### Container Creation After image creation containers are created based on that image and setup. @@ -133,67 +130,15 @@ This step executes the following: - Create the container with the specified properties. - Validate the container(s) were created successfully. -### Post container creation. +### Post Container Creation -- At the end of the container creation step, a set of commands are executed inside the **main** container `on-create-command`, `update-content-command` and `post-create-command`. This set of commands are executed in sequence on a container the first time its created and depending on the creation parameters received, [see here](devcontainerjson-reference.md#lifecycle-scripts) to learn more. By default `post-create-command` is executed in the background after reporting the successful creation of the development environment, this behavior depends on the `wait-for` property defined. +- At the end of the container creation step, a set of commands are executed inside the **main** container `on-create-command`, `update-content-command` and `post-create-command`. This set of commands are executed in sequence on a container the first time its created and depending on the creation parameters received, [see Devcontainer.json Reference - Lifecycle Scripts](devcontainerjson-reference.md#lifecycle-scripts) to learn more. By default `post-create-command` is executed in the background after reporting the successful creation of the development environment. +- If the `wait-for` property is defined then execution should stop at the specified property. -## Environment stop. +## Environment Stop Stops all containers in the environment. The intention of this step is to ensure all containers are stopped correctly to ensure no data is lost. ## Environment Restart After an environment has been stopped the containers are restarted according to the orchestrator defined. Additionally `post-start-command` is executed in the **main** container. - -## Environment Connection - -`devcontainer.json` has `post-attach-command` defined that should be executed after any tools attach to the container. These tools should call for the execution of this command. - -# Tool features - -Tools implementing this specification (like the reference implementation) are encouraged to support at least the following features: - -## Identification - -Tools implementing this specificaction should have a way to track what images and containers belong to a particular **development container** allowing the user to keep multiple on an environment and select which one to operate on. - -## Definition merge and validation -`read-configuration` - -This command should execute all validation tasks on the `devcontainer.json` format as defined [here](devcontainerjson-reference.md). - -## Image build -`build` - -Executes all steps of the lifecycle up to the build step. This allows users to take this images and publish them. - -## Environment creation -`up` - -Executes all steps required to obtain a working **development container**, executing tasks in the background as defined [here](#post-container-creation). - -## Stop -`stop` - -Executes a safe stop of all containers related to the **development container**. - -## Stop and Delete -`down` - -Executes stop and in addition deletes all containers related to the **development containers**. - -## Execute user commands -`run-user-commands` - -Runs the asynchronous commands on an environment according to paramenters received. It should be possible for the user to control which ones run. Namely: - -- `onCreate` -- `updateContent` -- `postCreateCommand` -- `postAttachCommand` -- `postStartCommand`. - -## Execute manual commands -`exec` - -Executes commands inside the **main** container of a development environment specified to the user. \ No newline at end of file From 78572b756b26b0faee65deec7c62da9989e7b5a9 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 09:51:46 -0700 Subject: [PATCH 03/10] Apply suggestions from code review Co-authored-by: Brigit Murtaugh --- docs/specs/devcontainer-reference.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md index 38989b07..d72a478a 100644 --- a/docs/specs/devcontainer-reference.md +++ b/docs/specs/devcontainer-reference.md @@ -1,14 +1,14 @@ # Dev container specification -The purpose of the **development container** specification is to provide a way to enrich containers with the needed content and metadata necessary to enable development inside them. This container **environments** should be easy to use, create and easy to recreate. +The purpose of the **development container** specification is to provide a way to enrich containers with the content and metadata necessary to enable development inside them. These container **environments** should be easy to use, create, and recreate. -A **development container** is a container that a user can use to develop an application inside of. Additionally, tools that want to implement this specification should provide a set of features/commands that give more flexibility to users and allow **development containers** to scale to large development groups. +A **development container** is a container in which a user can develop an application. Tools that want to implement this specification should provide a set of features/commands that give more flexibility to users and allow **development containers** to scale to large development groups. -An **environment** is defined as a logical instance of one or more **development containers** along with any needed side-car containers based on one set of metadata that can be managed as a single unit. Users can create multiple **environments** from the same configuration metadata for different purposes. +An **environment** is defined as a logical instance of one or more **development containers**, along with any needed side-car containers. An environment is based on one set of metadata that can be managed as a single unit. Users can create multiple **environments** from the same configuration metadata for different purposes. -Historically dev containers have been used to enable a development workflow used either locally or on the cloud and have been focused on using **Docker** or **docker-compose**. The intent of this specification and related tools is to expand the reach of **development containers**, allow the usage of containers by themselves or different orchestration technologies, and allow any tool to manage and create them. +Historically, dev containers have been used to enable a development workflow used either locally or in the cloud, and they've been focused on using **Docker** or **Docker Compose**. The intent of this specification and related tools is to expand the reach of **development containers**, allow the usage of containers by themselves or different orchestration technologies, and allow any tool to manage and create them. -The focus of the dev container specification is to describe how to enrich a container for the purposes of development rather than acting as a multi-container orchestrator format. Container orchestrator formats can be referenced, when needed, to manage multiple containers and the **Development container** lifecycle. 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. +The focus of the dev container specification is to describe how to enrich a container for the purposes of development, rather than acting as a multi-container orchestrator format. Container orchestrator formats can be referenced, when needed, to manage multiple containers and the **development container** lifecycle. 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. # Metadata From c5ca6107beacdba197c9f6a5343c94b8d98b6b63 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 09:56:15 -0700 Subject: [PATCH 04/10] Apply suggestions from code review Co-authored-by: Brigit Murtaugh --- docs/specs/devcontainer-reference.md | 47 ++++++++++++++-------------- 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md index d72a478a..738015fd 100644 --- a/docs/specs/devcontainer-reference.md +++ b/docs/specs/devcontainer-reference.md @@ -20,23 +20,22 @@ A **development container** is composed of a definition (e.g. contained in a `de The current metadata schema for **development containers** is contained in a `devcontainer.json` file. -The `devcontainer.json` specification contains different configuration options related to the underlying orchestrator format. At the same time this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. +The `devcontainer.json` specification contains different configuration options related to the underlying orchestrator format. At the same time, this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. # Configuration options -**Development containers** currently supports multiple ways to specify the containers that create an environment. The following section describes the differences between them. +**Development containers** currently support multiple ways to specify the containers that create an environment. The following section describes the differences between them. ## Image based -Image based configurations only reference an image that should be reachable and downloadable through `docker pull` commands. Logins and tokens required for these operations are execution environment specific.. The only required parameter is `image` . The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). - +Image based configurations only reference an image that should be reachable and downloadable through `docker pull` commands. Logins and tokens required for these operations are execution environment specific. The only required parameter is `image`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). ## Dockerfile based -These configurations are defined as using a `Dockerfile` to define the starting point of the **development containers**. As with image based configurations, it is assumed that any base images are already reachable by **docker** when performing a `docker build` command. The only required parameter in this case is the relative reference to the `Dockerfile` in `build.dockerfile`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). +These configurations are defined as using a `Dockerfile` to define the starting point of the **development containers**. As with image based configurations, it is assumed that any base images are already reachable by **Docker** when performing a `docker build` command. The only required parameter in this case is the relative reference to the `Dockerfile` in `build.dockerfile`. The details are [here](devcontainerjson-reference.md#image-or-dockerfile-specific-properties). -There are multiple properties that allow users to control `docker build` works: +There are multiple properties that allow users to control how `docker build` works: - `build.context` - `build.args` @@ -45,41 +44,41 @@ There are multiple properties that allow users to control `docker build` works: ## Docker Compose based -Docker compose configurations utilize `docker-compose` to create and manage a set of containers required for an application. As with the other configurations, any images required for this operation are assumed to be reachable. The required parameters are: +Docker Compose configurations use `docker-compose` to create and manage a set of containers required for an application. As with the other configurations, any images required for this operation are assumed to be reachable. The required parameters are: -- `build.dockerComposeFile` the reference to the docker-compose file(s) to be used. -- `service` this tag declares the **main** container that will be used for all other operations. Tools are assumed to also use this parameter to connect to the **development container** although they can provide facilities to connect to the other containers as required by the user. +- `build.dockerComposeFile`: the reference to the Docker Compose file(s) to be used. +- `service`: declares the **main** container that will be used for all other operations. Tools are assumed to also use this parameter to connect to the **development container**, although they can provide facilities to connect to the other containers as required by the user. It is important to remark that due to how `docker-compose` works a lot of the properties that apply to **image** and **dockerfile** configurations can’t be set by the application and thus must be set up manually by the user using the `docker-compose` format itself. --`runServices` are the set of services in the `docker-compose` configuration that should be started or stopped with the environment. +-`runServices`: the set of services in the `docker-compose` configuration that should be started or stopped with the environment. # Other options -In addition to the configuration options explained above there are other settings that apply when creating the **development containers** to facilitate their use by developers. These properties mostly apply to **image** and **dockerfile** based configurations. +In addition to the configuration options explained above, there are other settings that apply when creating **development containers** to facilitate their use by developers. These properties mostly apply to **image** and **Dockerfile** based configurations. -The main ones are: +We describe the main ones below. ## Environment Variables Environment variables can be set in containers at creation time, to override existing ones, or just to be used when a supporting tool connects to the environment. There are two kinds of environment variables: -Container. These variables are part of the container when it is created and are available at all points in its lifecycle. -Remote. This variables are to be set by a **development container** supporting tool as part of its environment when it runs. This variables can change during the lifetime of the container. +* Container: These variables are part of the container when it is created and are available at all points in its lifecycle. +* Remote: This variables are to be set by a **development container** supporting tool as part of its environment when it runs. These variables can change during the lifetime of the container. ## Mounts Mounts allow containers to have access to the underlying machine, share data between containers and to persist information between **development containers**. -It is important to note that these mounts are from the underlying compute environment and thus in cloud environments might not have access to the same data as a local machine. +It is important to note that these mounts are from the underlying compute environment and thus cloud environments might not have access to the same data as a local machine. ## Users -Users control the permissions of applications executed in the containers, allowing the developer to control them. The specification takes into account two types of user definuitions: +Users control the permissions of applications executed in the containers, allowing the developer to control them. The specification takes into account two types of user definitions: -Container User. The user that will be used for all operations that run inside a container. It is used to run lifecycle commands among others. -Remote User. In case the developer wants to use different users for different purposes, the remote user is the user that connecting tools should use to execute operations inside the container. +* Container User: The user that will be used for all operations that run inside a container. It is used to run lifecycle commands among others. +* Remote User: In case the developer wants to use different users for different purposes, the remote user is the user that connecting tools should use to execute operations inside the container. # Lifecycle @@ -107,13 +106,13 @@ The tasks executed when validating the configuration are: ### Initialization -During this step the following is executed: +During this step, the following is executed: - Validate access to the container orchestrator specified by the configuration. - Execution of `initializeCommand`. ### Image creation -The first part of an environment creation is generating the final image(s) that the **development containers** are going to use. This step is orchestrator dependent and can consist of just pulling a docker image, running docker build, or docker-compose build. Additionally this step is useful on its own since it permits the creation of intermediate images that can be uploaded and used by other users and thus cut down on creation time. It is encouraged that tools implementing this specification give access to a command that just executes this step. +The first part of environment creation is generating the final image(s) that the **development containers** are going to use. This step is orchestrator dependent and can consist of just pulling a Docker image, running Docker build, or docker-compose build. Additionally, this step is useful on its own since it permits the creation of intermediate images that can be uploaded and used by other users, thus cutting down on creation time. It is encouraged that tools implementing this specification give access to a command that just executes this step. This step executes the following: @@ -123,7 +122,7 @@ This step executes the following: ### Container Creation -After image creation containers are created based on that image and setup. +After image creation, containers are created based on that image and setup. This step executes the following: @@ -132,8 +131,8 @@ This step executes the following: ### Post Container Creation -- At the end of the container creation step, a set of commands are executed inside the **main** container `on-create-command`, `update-content-command` and `post-create-command`. This set of commands are executed in sequence on a container the first time its created and depending on the creation parameters received, [see Devcontainer.json Reference - Lifecycle Scripts](devcontainerjson-reference.md#lifecycle-scripts) to learn more. By default `post-create-command` is executed in the background after reporting the successful creation of the development environment. -- If the `wait-for` property is defined then execution should stop at the specified property. +- At the end of the container creation step, a set of commands are executed inside the **main** container: `on-create-command`, `update-content-command` and `post-create-command`. This set of commands is executed in sequence on a container the first time it's created and depending on the creation parameters received. You can learn more in the [documentation on lifecycle scripts](devcontainerjson-reference.md#lifecycle-scripts). By default, `post-create-command` is executed in the background after reporting the successful creation of the development environment. +- If the `wait-for` property is defined, then execution should stop at the specified property. ## Environment Stop @@ -141,4 +140,4 @@ Stops all containers in the environment. The intention of this step is to ensure ## Environment Restart -After an environment has been stopped the containers are restarted according to the orchestrator defined. Additionally `post-start-command` is executed in the **main** container. +After an environment has been stopped, the containers are restarted according to the orchestrator defined. Additionally, `post-start-command` is executed in the **main** container. From 92c11643c7c6935e4b2c3c7c65748c13f878e36f Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 17:26:22 +0000 Subject: [PATCH 05/10] Comments from PR. --- docs/specs/devcontainer-reference.md | 9 +++++ docs/specs/devcontainerjson-reference.md | 1 + docs/specs/supporting-tools.md | 48 ++++++++++++++---------- 3 files changed, 38 insertions(+), 20 deletions(-) diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md index 738015fd..3521cd0d 100644 --- a/docs/specs/devcontainer-reference.md +++ b/docs/specs/devcontainer-reference.md @@ -22,6 +22,14 @@ The current metadata schema for **development containers** is contained in a `de The `devcontainer.json` specification contains different configuration options related to the underlying orchestrator format. At the same time, this specification leaves space for further development and implementation of other orchestrator mechanisms and file formats. +While this metadata may be provided in different ways, when searching for a devcontainer.json file, products should expect to find a devcontainer.json file in one or more of the following locations (in order of precedence): + +.devcontainer/devcontainer.json +.devcontainer.json +.devcontainer/**/devcontainer.json (where ** is a sub-folder) + +It is valid that these files may exist in more than one location, so consider providing a mechanism for users to select one when appropriate. + # Configuration options @@ -103,6 +111,7 @@ The tasks executed when validating the configuration are: ## Environment Creation +The creation process goes through the steps necesarry to go from the user configuration to a working **environment** that is ready to be used. ### Initialization diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md index 69114d38..6e1ed197 100644 --- a/docs/specs/devcontainerjson-reference.md +++ b/docs/specs/devcontainerjson-reference.md @@ -21,6 +21,7 @@ The default locations of `devcontainer.json` file are relative to the `workspace | `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). | +| `customizations` | object | Product specific properties, defined in [supporting tools](supporting-tools.md) | ## Image or Dockerfile specific properties diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 6d3dcc54..a5caaef4 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -4,22 +4,39 @@ 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. -## Dev container CLI +## Editors -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. +### Visual Studio Code -The publishing of this CLI is being discussed in an [issue](https://github.com/microsoft/dev-container-spec/issues/9). +Visual studio code specific properties go under `vscode` inside `customizations`. -## GitHub Codespaces +| 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 `{}`. | + +Please note that Codespaces supports the VS Code properties. + +## Tools + +### Dev container CLI + +A dev container command line interface (CLI) that implements this specification is in development [here](https://github.com/devcontainers/cli). + +### 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. + +### 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 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 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). -### Product specific limitations +#### Product specific limitations Some properties may apply differently to Codespaces. @@ -33,22 +50,17 @@ Some properties may apply differently to Codespaces. | `shutdownAction` | enum | Does not apply to Codespaces. | | `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| -## Visual Studio Code 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 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. -### Product specific properties +#### Product specific properties -Some properties are specific to VS Code. Please note that Codespaces supports the VS Code properties. +Remote containers implements the [VS Code properties](#visual-studio-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 `{}`. | - -### Product specific limitations +#### Product specific limitations Some properties may also have certain limitations in the Remote - Containers extension. @@ -58,7 +70,3 @@ Some properties may also have certain limitations in the Remote - Containers ext | `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. | - -## 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. \ No newline at end of file From cf571d9b24e6fcc6f00dfdfecf69194f8d7e6281 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 19:02:19 +0000 Subject: [PATCH 06/10] Comments from PR. --- docs/specs/supporting-tools.md | 46 +++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index a5caaef4..f9ed32d3 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -15,7 +15,7 @@ Visual studio code specific properties go under `vscode` inside `customizations` | `extensions` | array | An array of extension IDs that specify the extensions that should be installed inside the container when it is created. Defaults to `[]`. | | `settings` | object | Adds default `settings.json` values into a container/machine specific settings file. Defaults to `{}`. | -Please note that Codespaces supports the VS Code properties. +Please note that [Remote - Containers](#visual-studio-code-remote---containers) and [GitHub Codespaces](#github-codespaces) support the VS Code properties. ## Tools @@ -27,6 +27,27 @@ A dev container command line interface (CLI) that implements this specification 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. +### 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 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. + +#### Product specific properties + +Remote containers implements the [VS Code properties](#visual-studio-code) specific properties. + +#### 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. | + ### 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. @@ -48,25 +69,4 @@ Some properties may apply differently to 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.| - -### 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 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. - -#### Product specific properties - -Remote containers implements the [VS Code properties](#visual-studio-code) specific properties. - -#### 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. | +| `${localEnv:VARIABLE_NAME}` | Any | For Codespaces, the host is in the cloud rather than your local machine.| \ No newline at end of file From 0f0034e3cd69ea72e63b91e72cd24472fbb54df9 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 19:06:18 +0000 Subject: [PATCH 07/10] Scaffolding for vscode. --- docs/specs/supporting-tools.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index f9ed32d3..46e5efc8 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -15,6 +15,18 @@ Visual studio code specific properties go under `vscode` inside `customizations` | `extensions` | array | An array of extension IDs that specify the extensions that should be installed inside the container when it is created. Defaults to `[]`. | | `settings` | object | Adds default `settings.json` values into a container/machine specific settings file. Defaults to `{}`. | +``` +"customizations": { + // Configure properties specific to VS Code. + "vscode": { + // Set *default* container specific settings.json values on container create. + "settings": { }, + "extensions": {}, + ] + } +} +``` + Please note that [Remote - Containers](#visual-studio-code-remote---containers) and [GitHub Codespaces](#github-codespaces) support the VS Code properties. ## Tools From 9439efb5bfba430c3627891f6ab848eed592a539 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 12:06:46 -0700 Subject: [PATCH 08/10] Update docs/specs/supporting-tools.md Co-authored-by: Brigit Murtaugh --- 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 46e5efc8..31a5975b 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -33,7 +33,7 @@ Please note that [Remote - Containers](#visual-studio-code-remote---containers) ### Dev container CLI -A dev container command line interface (CLI) that implements this specification is in development [here](https://github.com/devcontainers/cli). +A dev container command line interface (CLI) that implements this specification. It is in development in the [devcontainers/cli](https://github.com/devcontainers/cli) repo. ### Remote - Containers CLI From 9eb8f4695225298e174e20ef36575f3469b12364 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 19:33:43 +0000 Subject: [PATCH 09/10] Fixes --- docs/specs/supporting-tools.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 31a5975b..356e31c0 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -10,23 +10,25 @@ While most [dev container properties](devcontainerjson-reference.md) apply to an Visual studio code specific properties go under `vscode` inside `customizations`. -| 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 `{}`. | ``` "customizations": { // Configure properties specific to VS Code. "vscode": { // Set *default* container specific settings.json values on container create. - "settings": { }, - "extensions": {}, + "settings": {}, + "extensions": [], ] } } ``` + +| 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 `{}`. | + Please note that [Remote - Containers](#visual-studio-code-remote---containers) and [GitHub Codespaces](#github-codespaces) support the VS Code properties. ## Tools From 6776bfb31744843ef27918b94aba5fa5448b5e1b Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 24 May 2022 20:02:34 +0000 Subject: [PATCH 10/10] Typo --- docs/specs/supporting-tools.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md index 356e31c0..ba0fdc9b 100644 --- a/docs/specs/supporting-tools.md +++ b/docs/specs/supporting-tools.md @@ -18,7 +18,6 @@ Visual studio code specific properties go under `vscode` inside `customizations` // Set *default* container specific settings.json values on container create. "settings": {}, "extensions": [], - ] } } ```