Repository files navigation

This repository holds the dev container CLI, which can take a devcontainer.json and create and configure a dev container from it.

A development container allows you to use a container as a full-featured development environment. It can be used to run an application, to separate tools, libraries, or runtimes needed for working with a codebase, and to aid in continuous integration and testing. Dev containers can be run locally or remotely, in a private or public cloud.

This CLI is in active development. Current status:

• devcontainer build - Enables building/pre-building images
• devcontainer up - Spins up containers withdevcontainer.json settings applied
• devcontainer run-user-commands - Runs lifecycle commands likepostCreateCommand
• devcontainer read-configuration - Outputs current configuration for workspace
• devcontainer exec - Executes a command in a container withuserEnvProbe,remoteUser,remoteEnv, and other properties applied
• devcontainer features <...> - Tools to assist in authoring and testingDev Container Features
• devcontainer templates <...> - Tools to assist in authoring and testingDev Container Templates
• devcontainer stop - Stops containers
• devcontainer down - Stops and deletes containers

We'd love for you to try out the dev container CLI and let us know what you think. You can quickly try it out in just a few simple steps, either by installing its npm package or building the CLI repo from sources (see "Build from sources").

To install the npm package you will need Python and C/C++ installed to build one of the dependencies (see, e.g.,here for instructions).

npm install -g @devcontainers/cli

Verify you can run the CLI and see its help text:

devcontainer<command>Commands:  devcontainer up                   Create and run dev container  devcontainer build [path]         Build a dev container image  devcontainer run-user-commands    Run user commands  devcontainer read-configuration   Read configuration  devcontainer features             Features commands  devcontainer templates            Templates commands  devcontainerexec<cmd> [args..]  Execute acommand on a running dev containerOptions:  --help     Showhelp                                                 [boolean]  --version  Show version number                                       [boolean]

Once you have the CLI, you can try it out with a sample project, like thisRust sample.

Clone the Rust sample to your machine, and start a dev container with the CLI'sup command:

git clone https://github.com/microsoft/vscode-remote-try-rustdevcontainer up --workspace-folder<path-to-vscode-remote-try-rust>

This will download the container image from a container registry and start the container. Your Rust container should now be running:

[88 ms] dev-containers-cli 0.1.0.[165 ms] Start: Run: docker build -f /home/node/vscode-remote-try-rust/.devcontainer/Dockerfile -t vsc-vscode-remote-try-rust-89420ad7399ba74f55921e49cc3ecfd2 --build-arg VARIANT=bullseye /home/node/vscode-remote-try-rust/.devcontainer[+] Building 0.5s (5/5) FINISHED => [internal] load build definition from Dockerfile                       0.0s => => transferring dockerfile: 38B                                        0.0s => [internal] load .dockerignore                                          0.0s => => transferring context: 2B                                            0.0s => [internal] load metadatafor mcr.microsoft.com/vscode/devcontainers/r  0.4s => CACHED [1/1] FROM mcr.microsoft.com/vscode/devcontainers/rust:1-bulls  0.0s => exporting to image                                                     0.0s => => exporting layers                                                    0.0s => => writing image sha256:39873ccb81e6fb613975e11e37438eee1d49c963a436d  0.0s => => naming to docker.io/library/vsc-vscode-remote-try-rust-89420ad7399  0.0s[1640 ms] Start: Run: docker run --sig-proxy=false -a STDOUT -a STDERR --mount type=bind,source=/home/node/vscode-remote-try-rust,target=/workspaces/vscode-remote-try-rust -l devcontainer.local_folder=/home/node/vscode-remote-try-rust --cap-add=SYS_PTRACE --security-opt seccomp=unconfined --entrypoint /bin/sh vsc-vscode-remote-try-rust-89420ad7399ba74f55921e49cc3ecfd2-uid -cecho Container startedContainer started{"outcome":"success","containerId":"f0a055ff056c1c1bb99cc09930efbf3a0437c54d9b4644695aa23c1d57b4bd11","remoteUser":"vscode","remoteWorkspaceFolder":"/workspaces/vscode-remote-try-rust"}

You can then run commands in this dev container:

devcontainerexec --workspace-folder<path-to-vscode-remote-try-rust> cargo run

This will compile and run the Rust sample, outputting:

[33 ms] dev-containers-cli 0.1.0.   Compiling hello_remote_world v0.1.0 (/workspaces/vscode-remote-try-rust)    Finished dev [unoptimized + debuginfo] target(s)in 1.06s     Running`target/debug/hello_remote_world`Hello, VS Code Remote - Containers!{"outcome":"success"}

Congrats, you've just run the dev container CLI and seen it in action!

Theexample-usage folder contains some simple shell scripts to illustrate how the CLI can be used to:

• Inject tools for use inside a development container
• Use a dev container as your CI build environment to build an application (even if it is not deployed as a container)
• Build a container image from a devcontainer.json file that includesdev container features

This repository has adev container configuration, which you can use to ensure you have the right dependencies installed.

Compile the CLI with yarn:

yarnyarn compile

Verify you can run the CLI and see its help text:

node devcontainer.js --help

The dev container CLI is part of theDevelopment Containers Specification. This spec seeks to find ways to enrich existing formats with common development specific settings, tools, and configuration while still providing a simplified, un-orchestrated single container option – so that they can be used as coding environments or for continuous integration and testing.

Learn more on thedev container spec website.

You may review other resources part of the specification in thedevcontainers GitHub organization.

• Additional information on using the built-inFeatures testing command.

Check out how to contribute to the CLI inCONTRIBUTING.md.

This project is under anMIT license.