Skip to content

Clarify dev container CLIs #5212

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Mar 8, 2022
Merged

Clarify dev container CLIs #5212

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
86a52c1
Update CLI doc
Mar 4, 2022
3d5359e
Update containers doc
Mar 4, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/remote/containers.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
23 changes: 15 additions & 8 deletions docs/remote/devcontainer-cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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:

Expand All @@ -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:

Expand All @@ -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

Expand Down