From 86a52c1df89997e64e0134f284cc10cb323f684e Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 4 Mar 2022 14:13:19 -0800 Subject: [PATCH 1/2] Update CLI doc --- docs/remote/devcontainer-cli.md | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/docs/remote/devcontainer-cli.md b/docs/remote/devcontainer-cli.md index 0e7da0f435..f2d75bbf21 100644 --- a/docs/remote/devcontainer-cli.md +++ b/docs/remote/devcontainer-cli.md @@ -4,16 +4,23 @@ Area: remote TOCTitle: devcontainer CLI PageTitle: Installing and working with the devcontainer CLI ContentId: 8946213d-716e-41ca-955f-944a41c70353 -MetaDescription: Documentation on using the devcontainer command line interface with the Visual Studio Code Remote - Containers extension +MetaDescription: Documentation on using the VS Code devcontainer command line interface with the Visual Studio Code Remote - Containers extension DateApproved: 3/3/2022 --- -# devcontainer command line interface +# Development container command line interface +When we refer to a command line interface (CLI) for development containers, there are two varieties: +* "dev container CLI" - A reference implementation for the open dev container spec. The [current proposal](https://github.com/microsoft/dev-container-spec/issues/9) is to make a CLI available that can take a `devcontainer.json` and create and configure a dev container from it. It could be available in any IDE or editor. +* "Visual Studio Code `devcontainer` CLI" - A CLI that can be installed and used via the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or through an external terminal. -Given the growing number of use cases for dev containers, there is a companion `devcontainer` command line interface (CLI) that can be used independent of the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or GitHub Codespaces. This article will walk you through its installation and how to use it in different scenarios. +The former is in-progress. The latter is available today and the focus of this document. + +## Visual Studio Code `devcontainer` CLI + +Given the growing number of use cases for dev containers, there is a companion `devcontainer` CLI that can be used independent of the [Remote - Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or GitHub Codespaces. This article will walk you through its installation and how to use it in different scenarios. ## System requirements -To use the `devcontainer` CLI, you'll need the following on your system or CI/DevOps environment: +To use the VS Code `devcontainer` CLI, you'll need the following on your system or CI/DevOps environment: 1. [Node.js 14+](https://nodejs.org). 1. [The `docker` CLI](/docs/remote/containers#installation). @@ -70,7 +77,7 @@ Visual Studio Code has many [command line options](/docs/editor/command-line.md) ![Prompt to reopen folder within a dev container](images/devcontainer-cli/reopen-in-container.png) -With the devcontainer CLI, you can use the `devcontainer open` command to open the current folder straight into dev container mode, skipping the prompt. +With the VS Code `devcontainer` CLI, you can use the `devcontainer open` command to open the current folder straight into dev container mode, skipping the prompt. You can optionally specify the path to the folder to open, for example `devcontainer open /source/my-folder` to open the `/source/my-folder` folder within a dev container. @@ -169,7 +176,7 @@ jobs: docker push "${IMAGE_REPOSITORY}" ``` -### devcontainer CLI build options +### CLI build options The following options can be used with the `build` command: @@ -180,7 +187,7 @@ You can also type `devcontainer build --help` to see a full list of available op ### [Optional] Avoiding problems with images built using Docker -Given Dockerfiles and Docker Compose files can be used without VS Code or the `devcontainer` CLI, you may want to let users know that they should not try to build the image directly if it will not work as expected. To solve this problem, you can add a build argument that needs to be specified for things to work. +Given Dockerfiles and Docker Compose files can be used without VS Code or the VS Code `devcontainer` CLI, you may want to let users know that they should not try to build the image directly if it will not work as expected. To solve this problem, you can add a build argument that needs to be specified for things to work. For example, you could add the following to your Dockerfile: @@ -201,7 +208,7 @@ And the following in your `devcontainer.json`: } ``` -In the Docker Compose case, you can add this argument to a separate [override file to extend your configuration](/docs/remote/create-dev-container.md#extend-your-docker-compose-file-for-development) that is located in a different place in your source tree than the primary Docker Compose file +In the Docker Compose case, you can add this argument to a separate [override file to extend your configuration](/docs/remote/create-dev-container.md#extend-your-docker-compose-file-for-development) that is located in a different place in your source tree than the primary Docker Compose file. ## Next steps From 3d5359e747c81cfed3e7a0015b5c19742ca98bc1 Mon Sep 17 00:00:00 2001 From: bamurtaugh Date: Fri, 4 Mar 2022 14:15:02 -0800 Subject: [PATCH 2/2] Update containers doc --- docs/remote/containers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/remote/containers.md b/docs/remote/containers.md index 3b215b4af0..f5c14b870d 100644 --- a/docs/remote/containers.md +++ b/docs/remote/containers.md @@ -288,9 +288,9 @@ The **Remote-Containers: Configure Container Features** command allows you to up We recommend pre-building images with the tools you need rather than creating and building a container image each time you open your project in a dev container. Using pre-built images will result in a faster container startup, simpler configuration, and allows you to pin to a specific version of tools to improve supply-chain security and avoid potential breaks. You can automate pre-building your image by scheduling the build using a DevOps or continuous integration (CI) service like GitHub Actions. -We recommend using the [devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly. +We recommend using the [VS Code devcontainer CLI](/docs/remote/devcontainer-cli.md) to pre-build your images since it is kept in sync with the Remote - Container extension's latest capabilities - including [dev container features](#dev-container-features-preview). Once you've built your image, you can push it to a container registry (like the [Azure Container Registry](https://docs.microsoft.com/azure/container-registry/container-registry-get-started-docker-cli?tabs=azure-cli), [GitHub Container Registry](https://docs.github.com/packages/working-with-a-github-packages-registry/working-with-the-container-registry#pushing-container-images), or [Docker Hub](https://docs.docker.com/engine/reference/commandline/push)) and reference it directly. -See the [devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#building-a-dev-container-image) for more information. +See the [VS Code devcontainer CLI article on pre-building images](/docs/remote/devcontainer-cli.md#building-a-dev-container-image) for more information. ## Inspecting volumes