### Install Script Example Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md An example `install.sh` script demonstrating how to access and use the emitted environment variables. ```bash #!/usr/bin/env bash echo "Version is $VERSION" echo "Pip? $PIP" echo "Optimize? $OPTIMIZE" ``` -------------------------------- ### Hello World Dev Container Feature Install Script Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-11-01-author-a-feature.md The install script for a Dev Container Feature. This example sets up a 'hello' command that outputs a greeting. ```bash #!/bin/sh set -e echo "Activating feature 'hello'" GREETING=${GREETING:-undefined} echo "The provided greeting is: $GREETING" cat > /usr/local/bin/hello \ << EOF #!/bin/sh RED='\033[0;91m' NC='\033[0m' # No Color echo "${RED}${GREETING}, $(whoami)!${NC}" EOF chmod +x /usr/local/bin/hello ``` -------------------------------- ### Install Script Output Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md The output of the example `install.sh` script when run with the emitted environment variables. ```text Version is 3.10 Pip? false Optimize? true ``` -------------------------------- ### Detect OS and Architecture in Install Script Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-06-14-feature-authoring-best-practices.md Source /etc/os-release to get OS info and use dpkg to get the host architecture. This script checks for supported distribution versions and exits with an error if unsupported. ```bash # Source /etc/os-release to get OS info # Looks something like: # PRETTY_NAME="Debian GNU/Linux 11 (bullseye)" # NAME="Debian GNU/Linux" # VERSION_ID="11" # VERSION="11 (bullseye)" # VERSION_CODENAME=bullseye # ID=debian # HOME_URL="https://www.debian.org/" # SUPPORT_URL="https://www.debian.org/support" # BUG_REPORT_URL="https://bugs.debian.org/" . /etc/os-release # Store host architecture architecture="$(dpkg --print-architecture)" DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES="buster bullseye focal bionic xenial" if [[ "${DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES}" != *"${VERSION_CODENAME}"* ]]; then print_error "Unsupported distribution version '${VERSION_CODENAME}'. To resolve, either: (1) set feature option '\"moby\": false' , or (2) choose a compatible OS distribution" print_error "Supported distributions include: ${DOCKER_MOBY_ARCHIVE_VERSION_CODENAMES}" exit 1 fi ``` -------------------------------- ### Start a Dev Container Workspace Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md Clone a sample project and use the 'devcontainer up' command to build and start the development container. Replace '' with the actual path to your cloned project. ```bash git clone https://github.com/microsoft/vscode-remote-try-rust devcontainer up --workspace-folder ``` -------------------------------- ### Install Dev Container CLI with npm Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md Install the Dev Container CLI globally using npm. Ensure Node.js (version 14 or greater), Python, and C/C++ are installed as prerequisites. ```bash npm install -g @devcontainers/cli ``` -------------------------------- ### Install Tool in Remote User's Bin Folder Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-06-14-feature-authoring-best-practices.md Installs a tool into the effective remote user's bin directory, ensuring correct ownership and permissions. Uses environment variables like _REMOTE_USER_HOME and _REMOTE_USER. ```bash # Install tool in effective remoteUser's bin folder mkdir -p "$_REMOTE_USER_HOME/bin" curl $TOOL_DOWNLOAD_LINK -o "$_REMOTE_USER_HOME/bin/$TOOL" chown $_REMOTE_USER:$_REMOTE_USER "$_REMOTE_USER_HOME/bin/$TOOL" chmod 755 "$_REMOTE_USER_HOME/bin/$TOOL" ``` -------------------------------- ### Dev Container Feature Options Schema Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Example of a Feature's `devcontainer-feature.json` defining options for version, pip installation, and optimization. ```jsonc // ... "options": { "version": { "type": "string", "enum": ["latest", "3.10", "3.9", "3.8", "3.7", "3.6"], "default": "latest", "description": "Select a Python version to install." }, "pip": { "type": "boolean", "default": true, "description": "Installs pip" }, "optimize": { "type": "boolean", "default": true, "description": "Optimize python installation" } } ``` -------------------------------- ### Dev Container Feature File Structure Example Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features-distribution.md This example illustrates the recommended directory structure for a Dev Container Features collection within a git repository. It includes source code for features, metadata files, and optional test scripts. ```bash . \ ├── README.md \ ├── src \ │ ├── dotnet \ │ │ ├── devcontainer-feature.json \ │ │ ├── install.sh \ │ │ └── ... \ │ ├ \ │ ├── go \ │ │ ├── devcontainer-feature.json \ │ │ └── install.sh \ │ ├── ... \ │ │ ├── devcontainer-feature.json \ │ │ └── install.sh \ ├── test \ │ ├── dotnet \ │ │ ├── test.sh \ │ │ └── ... \ │ └── go \ │ | └── test.sh \ │ ├── ... \ │ │ └── test.sh \ ├── ... ``` -------------------------------- ### Dev Container CLI Help Text Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md View available commands and options for the Dev Container CLI after installation. This helps in understanding the CLI's capabilities. ```bash devcontainer 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 [args..] Execute a command on a running dev container Options: --help Show help [boolean] --version Show version number [boolean] ``` -------------------------------- ### Dev Container Build and Run Output Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md This output shows the process of building a Docker image for a dev container and starting the container. It includes build steps and confirmation of container startup. ```log [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"} ``` -------------------------------- ### Serve Jekyll Site Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/README.md Execute this command within the dev container to start the Jekyll site. Ensure the dev container is built and running. ```shell bundle exec jekyll serve ``` -------------------------------- ### Hello World Dev Container Feature JSON Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-11-01-author-a-feature.md Defines the metadata and options for a Dev Container Feature. Use this for a basic 'Hello, World!' example. ```json { "name": "Hello, World!", "id": "hello", "version": "1.0.2", "description": "A hello world feature", "options": { "greeting": { "type": "string", "proposals": [ "hey", "hello", "hi", "howdy" ], "default": "hey", "description": "Select a pre-made greeting, or enter your own" } } } ``` -------------------------------- ### Example Collection Index Entry Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-11-01-author-a-feature.md Demonstrates the correct format for an entry in the collection-index.yml file. The ociReference should point to the collection namespace root, not an individual feature. ```yaml ociReference: ghcr.io// ``` -------------------------------- ### Development Container Dockerfile Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-02-15-gitlab-ci.md Sets up the base Python environment and installs necessary packages for a CDK project. Ensure Python and pip are available. ```dockerfile FROM mcr.microsoft.com/devcontainers/python:latest RUN pip3 --disable-pip-version-check --no-cache-dir install aws_cdk_lib constructs jsii pylint \ && rm -rf /tmp/pip-tmp ``` -------------------------------- ### Renaming a Feature - Current Configuration Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Example of a `devcontainer-feature.json` for a Feature named 'docker-from-docker'. ```jsonc { "id": "docker-from-docker", "version": "2.0.1", "name": "Docker (Docker-from-Docker)", "documentationURL": "https://github.com/devcontainers/features/tree/main/src/docker-from-docker", .... } ``` -------------------------------- ### User Input for Template Options Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates.md Example of user-selected values for template options, used by supporting tools to generate the final configuration. This demonstrates how user choices map to specific template configurations. ```json { imageVariant:"17-bullseye", nodeVersion: "latest", installMaven: "false" } ``` -------------------------------- ### Reference Dev Container Features in devcontainer.json Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Use the `features` object to specify which Features to install. Each key is a Feature identifier, and the value is an object of options or an empty object for defaults. Features are installed in an order determined by specific rules. ```jsonc "features": { "ghcr.io/user/repo/go": {}, "ghcr.io/user/repo1/go:1": {}, "ghcr.io/user/repo2/go:latest": {}, "https://github.com/user/repo/releases/devcontainer-feature-go.tgz": { "optionA": "value" }, "./myGoFeature": { "optionA": true, "optionB": "hello", "version" : "1.0.0" } } ``` -------------------------------- ### Example GHCR Package Settings URL Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-11-01-author-a-feature.md Illustrates the URL structure for accessing the settings page of a GHCR container package, used for changing its visibility to public. ```text https://github.com/users//packages/container/%2F/settings ``` -------------------------------- ### User devcontainer.json Feature Configuration Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Example of a user's `devcontainer.json` specifying options for the Python feature. ```jsonc "features": { "ghcr.io/devcontainers/features/python:1": { "version": "3.10", "pip": false } } ``` -------------------------------- ### Writing a Script to a Persistent Container Path Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md This example shows how a Feature can write a script to a known, persistent path within the container for later use in lifecycle hooks. The script is then executed during the `postCreateCommand`. ```bash PULL_GIT_LFS_SCRIPT_PATH="/usr/local/share/pull-git-lfs-artifacts.sh" tee "$PULL_GIT_LFS_SCRIPT_PATH" > /dev/null \ << EOF #!/bin/sh set -e <...truncated...> EOF ``` ```json { "id": "git-lfs", "version": "1.1.0", "name": "Git Large File Support (LFS)", // <...truncated...> "postCreateCommand": "/usr/local/share/pull-git-lfs-artifacts.sh", "installsAfter": [ "ghcr.io/devcontainers/features/common-utils" ] } ``` -------------------------------- ### Example GHCR Feature Reference Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-11-01-author-a-feature.md Shows how a published feature can be referenced in a devcontainer.json file. Assumes the feature is prefixed with the owner/repo namespace. ```json ghcr.io/devcontainers/feature-starter/color:1 ``` -------------------------------- ### Set Container Security Options with securityOpt Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/json_reference.md Use to set container security options. For example, setting seccomp to unconfined. ```json "securityOpt": [ "seccomp=unconfined" ] ``` -------------------------------- ### Define Soft Dependencies with installsAfter Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Use `installsAfter` in a Feature's `devcontainer-feature.json` to influence the installation order of already queued Features. This is a soft dependency and is not evaluated recursively. ```json { "name": "My Feature", "id": "myFeature", "version": "1.0.0", "installsAfter": [ "foo", "bar" ] } ``` -------------------------------- ### Push Dev Container Collection to OCI Registry Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates-distribution.md This example shows how to push the `devcontainer-collection.json` file to an OCI registry. The collection file is tagged as 'latest' and uses a specific media type for collections. The namespace should match the template namespace. ```bash # ghcr.io/devcontainers/templates REGISTRY=ghcr.io NAMESPACE=devcontainers/templates oras push ${REGISTRY}/${NAMESPACE}:latest \ --config /dev/null:application/vnd.devcontainers \ ./devcontainer-collection.json:application/vnd.devcontainers.collection.layer.v1+json ``` -------------------------------- ### Create a Custom Dockerfile Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-12-16-dockerfile.md Define a Dockerfile to extend a base image, install OS packages, or make other modifications. This file should be placed alongside your devcontainer.json. ```Dockerfile FROM mcr.microsoft.com/devcontainers/base:ubuntu # Install the xz-utils package RUN apt-get update && apt-get install -y xz-utils ``` -------------------------------- ### Dev Container Template File Structure Example Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates-distribution.md Illustrates the typical file structure for a Dev Container Template collection within a git repository. Each template resides in its own sub-directory under 'src', containing metadata and configuration files. ```plaintext . ├── README.md ├── src │ ├── dotnet │ │ ├── devcontainer-template.json │ │ ├── .devcontainer.json │ │ ├── ... │ ├ │ ├── docker-from-docker │ │ ├── devcontainer-template.json │ │ ├── .devcontainer │ │ ├── devcontainer.json │ │ ├── Dockerfile │ │ └── ... │ │ ├── ... │ ├ │ ├── go-postgres │ │ ├── devcontainer-template.json │ │ ├── .devcontainer │ │ ├── devcontainer.json │ │ ├── docker-compose.yml │ │ ├── Dockerfile │ │ └── ... │ │ ├── ... ``` -------------------------------- ### Bootstrap Script for Scripting Language Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-06-14-feature-authoring-best-practices.md This script checks if it's run as root and installs bash on Alpine images before executing the main script using bash. Use plain /bin/sh if bash is not guaranteed. ```sh #!/bin/sh # ... # ... if [ "$(id -u)" -ne 0 ]; then echo -e 'Script must be run as root. Use sudo, su, or add "USER root" to your Dockerfile before running this script.' exit 1 fi # If we're using Alpine, install bash before executing . /etc/os-release if [ "${ID}" = "alpine" ]; then apk add --no-cache bash fi exec /bin/bash "$(dirname $0)/main.sh" "$@" exit $? ``` -------------------------------- ### Push Dev Container Template to OCI Registry Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates-distribution.md This example demonstrates how to push a Dev Container Template to an OCI registry using `oras`. It iterates through different version tags, including 'latest'. Ensure the artifact path points to your packaged template. ```bash # ghcr.io/devcontainers/templates/go:1 REGISTRY=ghcr.io NAMESPACE=devcontainers/templates TEMPLATE=go ARTIFACT_PATH=devcontainer-template-go.tgz for VERSION in 1 1.2 1.2.3 latest do oras push ${REGISTRY}/${NAMESPACE}/${TEMPLATE}:${VERSION} \ --config /dev/null:application/vnd.devcontainers \ ./${ARTIFACT_PATH}:application/vnd.devcontainers.layer.v1+tar done ``` -------------------------------- ### Docker Compose with PostgreSQL Service Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-12-16-dockerfile.md Defines a multi-container setup using Docker Compose. It includes a Dev Container service using a base image and a PostgreSQL service. The Dev Container is networked to the database service. ```yaml version: '3.8' services: devcontainer: image: mcr.microsoft.com/devcontainers/base:ubuntu volumes: - ../..:/workspaces:cached network_mode: service:db command: sleep infinity db: image: postgres:latest restart: unless-stopped volumes: - postgres-data:/var/lib/postgresql/data environment: POSTGRES_PASSWORD: postgres POSTGRES_USER: postgres POSTGRES_DB: postgres volumes: postgres-data: ``` -------------------------------- ### Push Feature to OCI Registry using oras Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features-distribution.md This example demonstrates how to push a Feature artifact to an OCI registry using the `oras` tool. It iterates through different version tags for the Feature. Ensure the artifact path points to your packaged Feature tarball. ```bash # ghcr.io/devcontainers/features/go:1 REGISTRY=ghcr.io NAMESPACE=devcontainers/features FEATURE=go ARTIFACT_PATH=devcontainer-feature-go.tgz for VERSION in 1 1.2 1.2.3 latest do oras push ${REGISTRY}/${NAMESPACE}/${FEATURE}:${VERSION} \ --config /dev/null:application/vnd.devcontainers \ ./${ARTIFACT_PATH}:application/vnd.devcontainers.layer.v1+tar done ``` -------------------------------- ### Example OCI Image Manifest with Metadata Annotation Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features-distribution.md This JSON object represents an OCI image manifest. It includes custom media types for Dev Container Features and a crucial `dev.containers.metadata` annotation containing the escaped JSON of the `devcontainer-feature.json`. ```json { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "config": { "mediaType": "application/vnd.devcontainers", "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "size": 0 }, "layers": [ { "mediaType": "application/vnd.devcontainers.layer.v1+tar", "digest": "sha256:738af5504b253dc6de51d2cb1556cdb7ce70ab18b2f32b0c2f12650ed6d2e4bc", "size": 3584, "annotations": { "org.opencontainers.image.title": "devcontainer-feature-myFeature.tgz" } } ], "annotations": { "dev.containers.metadata": "{\"name\": \"My Feature\",\"id\": \"myFeature\",\"version\": \"1.0.0\",\"dependsOn\": {\"ghcr.io/myotherFeature:1\": {\"flag\": true},\"features.azurecr.io/aThirdFeature:1\": {},\"features.azurecr.io/aFourthFeature:1.2.3\": {}}}" } } ``` -------------------------------- ### Override Feature Install Order with overrideFeatureInstallOrder Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/json_reference.md Allows you to override the Feature install order when needed. By default, Features will attempt to automatically set the order they are installed based on a installsAfter property within each of them. ```json "overrideFeatureInstallОrder": [ "ghcr.io/devcontainers/features/common-utils", "ghcr.io/devcontainers/features/github-cli" ] ``` -------------------------------- ### Override Feature Installation Order Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Use `overrideFeatureInstallOrder` in `devcontainer.json` to specify a descending priority order for Feature installation. This must be consistent with the resolved dependency graph. ```javascript const roundPriority = { "foo": 3, "bar": 2, "baz": 1 } ``` -------------------------------- ### Configure Initial Files to Open in Codespaces Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/supporting.md Customize which files are opened and activated when a codespace is created using the `codespaces.openFiles` property. Paths are relative to the repository root. ```json "customizations": { // Configure properties specific to Codespaces. "codespaces": { "openFiles": [ "README" "src/index.js" ] } } ``` -------------------------------- ### Initialize Command Configuration Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/json_schema.md Specifies a command to run on the host machine during initialization. Can be a single string for shell execution or an array for direct execution. ```json { "initializeCommand": "echo 'Initializing...'" } ``` ```json { "initializeCommand": [ "echo", "Initializing..." ] } ``` -------------------------------- ### Renaming a Feature - Updated Configuration Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Example of an updated `devcontainer-feature.json` after renaming a Feature to 'docker-outside-of-docker', including `legacyIds`. ```jsonc { "id": "docker-outside-of-docker", "version": "2.0.2", "name": "Docker (Docker-outside-of-Docker)", "documentationURL": "https://github.com/devcontainers/features/tree/main/src/docker-outside-of-docker", "legacyIds": [ "docker-from-docker" ] .... } ``` -------------------------------- ### Create Container Command Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/json_schema.md Defines a command to execute when the container is created, after initialization. Supports string, array, or object formats. ```json { "onCreateCommand": "apt-get update && apt-get install -y some-package" } ``` ```json { "onCreateCommand": [ "apt-get", "update", "&&", "apt-get", "install", "-y", "some-package" ] } ``` -------------------------------- ### Modify PATH in Dev Container Feature Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-06-14-feature-authoring-best-practices.md Use `containerEnv` in `devcontainer-feature.json` to prepend a directory to the PATH. This is useful for making installed tools accessible. ```json { "containerEnv": { "PATH": "/usr/local/myTool/bin:${PATH}" } } ``` -------------------------------- ### Build and Push Dev Container Image Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md Use the Dev Container CLI to build and push your development container image. This command automates the process of creating a pre-built image that can be referenced directly. ```bash devcontainer build --workspace-folder . --push true --image-name : ``` -------------------------------- ### Reference Prebuilt Image in devcontainer.json Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/reference.md Simplify your devcontainer.json by referencing a prebuilt image. The image metadata will be automatically picked up, including configuration and Feature metadata. ```json { "image": "mcr.microsoft.com/devcontainers/go:1" } ``` -------------------------------- ### Configure Dev Container to Build from Dockerfile Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2022-12-16-dockerfile.md In devcontainer.json, remove the 'image' property and add 'build' with the 'dockerfile' property pointing to your Dockerfile. This tells the Dev Container CLI to build the image from your Dockerfile. ```json { "build": { // Path is relative to the devcontainer.json file. "dockerfile": "Dockerfile" } } ``` -------------------------------- ### Post Create Command Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/json_schema.md Defines a command to execute after the container has been created. Supports string, array, or object formats. ```json { "postCreateCommand": "chmod +x ./entrypoint.sh" } ``` ```json { "postCreateCommand": [ "chmod", "+x", "./entrypoint.sh" ] } ``` -------------------------------- ### Publish Dev Container Templates Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates-distribution.md Publishes each Template in the specified directory to the given registry and namespace. Ensure GITHUB_TOKEN is set with package write permissions for private registries. ```bash GITHUB_TOKEN="$CR_PAT" devcontainer templates publish -r ghcr.io -n devcontainers/templates ./src ``` -------------------------------- ### Configure VS Code Customizations in devcontainer.json Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/supporting.md Use the `vscode` property within `customizations` to set default `settings.json` values and specify extensions to be installed in the dev container. ```json "customizations": { // Configure properties specific to VS Code. "vscode": { // Set *default* container specific settings.json values on container create. "settings": {}, "extensions": [] } } ``` -------------------------------- ### Define Hard Dependencies with dependsOn Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md Use `dependsOn` in a Feature's `devcontainer-feature.json` to declare required dependencies. These must be installed before the current Feature. Dependencies can specify options or be empty. ```json { "name": "My Feature", "id": "myFeature", "version": "1.0.0", "dependsOn": { "foo:1": { "flag": true }, "bar:1.2.3": {}, "baz@sha256:a4cdc44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855": {} } } ``` -------------------------------- ### Dev Container Template Folder Structure Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates.md Illustrates the basic folder structure for a Dev Container Template, including required metadata and configuration files. ```plaintext +-- template | +-- devcontainer-template.json | +-- .devcontainer.json | +-- (other files) ``` -------------------------------- ### Option Name Transformation Logic Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md This JavaScript function transforms option names to be valid environment variables by replacing invalid characters with underscores and ensuring they do not start with digits or underscores. ```javascript (str: string) => str .replace(/[^-]/g, '_') .replace(/^[0-9_]+/g, '_') .toUpperCase(); ``` -------------------------------- ### Dev Container Configuration with Template Options Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates.md Shows how template options are referenced and substituted within a .devcontainer.json file. Used to dynamically configure the development environment based on user selections. ```json { "name": "Java", "image": "mcr.microsoft.com/devcontainers/java:0-${templateOption:imageVariant}", "features": { "ghcr.io/devcontainers/features/node:1": { "version": "${templateOption:nodeVersion}", "installMaven": "${templateOption:installMaven}" } }, // ... } ``` -------------------------------- ### GitHub Actions Workflow for Feature Testing Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-06-14-feature-authoring-best-practices.md A GitHub Actions workflow to test devcontainer features against a matrix of base images. It installs the devcontainer CLI and runs tests using `devcontainer features test`. ```yaml name: "Test Features matrixed with a set of base images" on: push: branches: - main workflow_dispatch: jobs: test: runs-on: ubuntu-latest continue-on-error: true strategy: matrix: features: [ "anaconda", "aws-cli", "azure-cli", # ... ] baseImage: [ "ubuntu:bionic", "ubuntu:focal", "ubuntu:jammy", "debian:11", "debian:12", "mcr.microsoft.com/devcontainers/base:ubuntu", "mcr.microsoft.com/devcontainers/base:debian", ] steps: - uses: actions/checkout@v3 - name: "Install latest devcontainer CLI" run: npm install -g @devcontainers/cli - name: "Generating tests for '${{ matrix.features }}' against '${{ matrix.baseImage }}'" run: devcontainer features test --skip-scenarios -f ${{ matrix.features }} -i ${{ matrix.baseImage }} ``` -------------------------------- ### Reference Prebuilt Image in devcontainer.json Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_posts/2023-08-22-prebuild.md Use a prebuilt image by referencing its URL in your devcontainer.json file. This allows you to leverage existing container images for your development environment. ```json "image": "ghcr.io/craiglpeters/kubernetes-devcontainer:latest" ``` -------------------------------- ### Dev Container Feature Folder Structure Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/features.md A Dev Container Feature is organized in a folder containing at least a `devcontainer-feature.json` metadata file and an `install.sh` script for installation logic. Additional files can be included and will be packaged with the feature. ```shell +-- feature | +-- devcontainer-feature.json | +-- install.sh | +-- (other files) ``` -------------------------------- ### Configure Repository Permissions for Codespaces Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/supporting.md Use the `codespaces.repositories` property to grant your codespace access to other repositories. Specify the repository and the required permissions. ```json "customizations": { // Configure properties specific to Codespaces. "codespaces": { "repositories": { "my_org/my_repo": { "permissions": { "issues": "write" } } } } } ``` -------------------------------- ### Parallel PostCreateCommand Execution Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/spec.md Use an object for lifecycle scripts to run multiple commands in parallel. The keys are unique names for the commands, and values are the commands themselves (string or array). ```json { "postCreateCommand": { "server": "npm start", "db": ["mysql", "-u", "root", "-p", "my database"] } } ``` -------------------------------- ### Modified Dev Container Configuration Source: https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_implementors/templates.md Illustrates the resulting .devcontainer.json file after template options have been substituted with user-selected values. This shows the final configuration applied to the project. ```json { "name": "Go", "image": "mcr.microsoft.com/devcontainers/go:0-17-bullseye", "features": { "ghcr.io/devcontainers/features/node:1": { "version": "latest", "installMaven": "false" } }, ... } ```