/devcontainers-templates

Repository for Dev Container Templates that are managed by Dev Container spec maintainers. See https://github.com/devcontainers/template-starter to create your own!

Primary LanguageShellMIT LicenseMIT

Development Container Templates

devcontainers organization logo Development Container Templates
A simple set of dev container 'templates' to help get you up and running with a containerized environment.

A development container is a running Docker container with a well-defined tool/runtime stack and its prerequisites. It allows you to use a container as a full-featured development environment which 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.

This repository contains a set of Dev Container Templates which are source files packaged together that encode configuration for a complete development environment. A Template can be used in a new or existing project, and a supporting tool will use the configuration from the template to build a development container.

Contents

  • src - A collection of subfolders, each declaring a template. Each subfolder contains at least a devcontainer-template.json and a devcontainer.json.
  • test - Mirroring src, a folder-per-template with at least a test.sh script. These tests are executed by the CI.

How can I use the Templates?

1. Using supporting tools

A variety of tools and services support the Dev Container Spec, and they may provide direct integrations with the Templates in this repo. For instance, Visual Studio Code and GitHub Codespaces provide a user-friendly interface to configure the Templates hosted in this repository, as well as the community-contributed Templates. Additionally, you can customize your dev container with additional available Features.

For more information, please refer to the following documents for VS Code and Github Codespaces.

2. Using the Dev Container CLI

The @devcontainers/cli offers a devcontainer templates apply command to apply a Template hosted in the supported OCI registry.

devcontainer templates apply

Apply a template to the project

Options:
      --help              Show help                                                                            [boolean]
      --version           Show version number                                                                  [boolean]
  -w, --workspace-folder  Target workspace folder to apply Template                   [string] [required] [default: "."]
  -t, --template-id       Reference to a Template in a supported OCI registry                        [string] [required]
  -a, --template-args     Arguments to replace within the provided Template, provided as JSON   [string] [default: "{}"]
  -f, --features          Features to add to the provided Template, provided as JSON.           [string] [default: "[]"]
      --log-level         Log level.                               [choices: "info", "debug", "trace"] [default: "info"]
      --tmp-dir           Directory to use for temporary files. If not provided, the system default will be inferred.
                                                                                                                [string]

Example

devcontainer templates apply --workspace-folder . \
    --template-id ghcr.io/devcontainers/templates/cpp:latest \
    --template-args '{ "imageVariant": "debian-12" }' \
    --features '[{ "id": "ghcr.io/devcontainers/features/azure-cli:1", "options": { "version" : "1" } }]'

Contributions

Creating your own collection of templates

The Dev Container Template specification outlines a pattern for community members and organizations to self-author Templates in repositories they control.

A starter repository devcontainers/template-starter and GitHub Action are available to help bootstrap self-authored Templates.

We are eager to hear your feedback on self-authoring! Please provide comments and feedback on spec issue #71.

Contributing to this repository

This repository will accept improvement and bug fix contributions related to the current set of maintained templates.

Feedback

Issues related to these templates can be reported in an issue in this repository.

License

Copyright (c) Microsoft Corporation. All rights reserved.
Licensed under the MIT License. See LICENSE.