Essential Resources
- https://github.com/devcontainers/templates
- https://github.com/devcontainers/cli
Understanding the Repository's Primary Purpose
The devcontainers/templates repository represents Microsoft's official collection of Development Container definitions and templates. This centralized resource enables developers to rapidly establish standardized development environments—whether operating locallly or deploying to cloud infrastructure. By leveraging Docker alongside VS Code's remote development capabilities, teams can achieve environment consistency while maintaining cross-platform compatibility, including web-based access through GitHub Codespaces. #### Key Capabilities
Development Containers leverage Docker to create standardized development environments that, when combined with VS Code's Remote - Containers extension, deliver: - Consistent cross-platform experiences (identical behavior across Windows, macOS, and Linux);
- Pre-configured toolchains and dependencies available immediately (Go, .NET, C++, Python, and other language environments);
- Isolated project dependencies that prevent pollution of the host system.
Repository Structure
| Directory/File | Purpose |
|---|---|
containers/ |
Multi-language and framework templates (Go, .NET, C++, Python, Docker-in-Docker configurations) |
repository-containers/ |
Tailored configurations for specific projects like VS Code, TensorFlow, and CPython |
script-library/ |
Reusable scripts for common setup tasks (zsh installation, Node.js, desktop environments) |
build/ |
Build automation scripts for publishing images to Microsoft's Container Registry |
.devcontainer/ |
Self-referential configuration used for developing and maintaining the repository itself |
Migration Notice: The original vscode-dev-containers repository has been archived and migrated to the new devcontainers/spec and devcontainers/cli ecosystem. New projects should reference the updated repositories.
Setting Up and Using Dev Containers Locally
The primary value lies in reusing pre-built container configurations. Local deployment requires meeting prerequisites and following core setup steps. #### Prerequisites
- Docker Desktop installed on your system;
- VS Code with the Dev Containers extension installed;
- Git (optional but recommended for cloning repositories).
Core Usage Patterns
Pattern 1: Using Existing Templates (Recommended)
To quickly bootstrap a Go development environment: 1. Clone the repository locally: git clone https://github.com/devcontainers/templates.git cd templates
2. Navigate to the template directory, such as containers/go/.devcontainer/, which contains both devcontainer.json and Dockerfile;
3. Open the folder in VS Code and press F1 or Ctrl/Cmd + Shift + P, then execute Dev Containers: Reopen in Container;
4. VS Code automatically builds or pulls the container image, starts the enviroment, and connects to it—all with Go toolchain and VS Code Go extension pre-installed.
Pattern 2: Customizing Your Own Dev Container
Adapt an existing template for your project's specific needs. Using .NET as an example: 1. Copy the template directory containers/dotnet/.devcontainer/ to your project root;
2. Modify devcontainer.json parameters as needed: { "build": { "dockerfile": "Dockerfile", "args": { "VARIANT": "8.0-bullseye" } } }
3. Execute Dev Containers: Reopen in Container to build your customized container.
Pattern 3: Utilizing Pre-built Images
The ecosystem provides numerous pre-built images hosted on Microsoft's Container Registry. Reference them direct in your devcontainer.json: ```
{
"name": "VS Code Dev",
"image": "mcr.microsoft.com/vscode/devcontainers/base:ubuntu"
}
### Important Considerations
1. **Migration Path:** Since the original repository is archived, new projects should prioritize using the devcontainers/templates ecosystem for ongoing support and updates;
2. **Permission Configuration:** Certain containers require elevated privileges (`--privileged` or `SYS_PTRACE`) for debugging capabilities. Configure these in `devcontainer.json`'s `runArgs` property;
3. **Non-root Users:** Containers run as non-root users (`vscode` or `node`) by default. To run as root, modify or remove the `remoteUser` configuration;
4. **Codespaces Compatibility:** Configurations under `repository-containers/` may not be compatible with GitHub Codespaces and are intended for local development only.
### Testing the Repository's Own Dev Container
The repository includes a nested-container debugging environment (inception pattern): 1. Open the root-level `.devcontainer/` directory;
2. Execute **Reopen in Container** to launch a debugging environment with integrated desktop support;
3. Press `F1` → **Ports: Focus on Ports View** to access ports 6080/5901, then connect to view the container's desktop interface (password: `vscode`).
This repository serves as a comprehensive template library for Development Containers. Fully deployable and reusable locally, it demonstrates how Docker combined with VS Code extensions creates standardized, reproducible development environments suitable for teams of any size.