gem-hunter
Language: TypeScript
A reference implementation for the specification that can create and configure a dev container from a devcontainer.json.
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 imagesdevcontainer up - Spins up containers with devcontainer.json settings applieddevcontainer run-user-commands - Runs lifecycle commands like postCreateCommanddevcontainer read-configuration - Outputs current configuration for workspacedevcontainer exec - Executes a command in a container with userEnvProbe, remoteUser, remoteEnv, and other properties applieddevcontainer outdated - Show outdated lockfile featuresdevcontainer upgrade - Upgrade lockfile featuresdevcontainer features <...> - Tools to assist in authoring and testing Dev Container Featuresdevcontainer templates <...> - Tools to assist in authoring and testing Dev Container Templatesdevcontainer stop - Stops containersdevcontainer down - Stops and deletes containersLockfiles (.devcontainer-lock.json) are generated by default when running build or up to pin feature versions for reproducible builds. Use --no-lockfile to opt out, or --frozen-lockfile to enforce an existing lockfile.
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 using the install script, installing its npm package, or building the CLI repo from sources (see "Build from sources").
You can install the CLI with a standalone script that downloads a bundled Node.js runtime, so no pre-installed Node.js is required. It works on Linux and macOS (x64 and arm64):
curl -fsSL https://raw.githubusercontent.com/devcontainers/cli/main/scripts/install.sh | shThen add the install location to your PATH:
export PATH="$HOME/.devcontainers/bin:$PATH"
You can also specify a version, a custom install directory, or update/uninstall an existing installation:
# Install a specific version sh install.sh --version 0.82.0 # Install to a custom directory sh install.sh --prefix ~/.local/devcontainers # Update to latest sh install.sh --update # Uninstall sh install.sh --uninstall
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 devcontainer exec <cmd> [args..] Execute a command on a running dev container Options: --help Show help [boolean] --version Show version number [boolean]
Once you have the CLI, you can try it out with a sample project, like this Rust sample.
Clone the Rust sample to your machine, and start a dev container with the CLI's up command:
git clone https://github.com/microsoft/vscode-remote-try-rust devcontainer 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 metadata for 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 -c echo Container started Container started {"outcome":"success","containerId":"f0a055ff056c1c1bb99cc09930efbf3a0437c54d9b4644695aa23c1d57b4bd11","remoteUser":"vscode","remoteWorkspaceFolder":"/workspaces/vscode-remote-try-rust"}
You can then run commands in this dev container:
devcontainer exec --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!
The example-usage folder contains some simple shell scripts to illustrate how the CLI can be used to:
This repository has a dev container configuration, which you can use to ensure you have the right dependencies installed.
Compile the CLI with yarn:
yarn yarn compile
Verify you can run the CLI and see its help text:
node devcontainer.js --help
The dev container CLI is part of the Development 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 the dev container spec website.
You may review other resources part of the specification in the devcontainers GitHub organization.
Check out how to contribute to the CLI in CONTRIBUTING.md.
This project is under an MIT license.