Byte Bound Report
Dev Tools

Devcontainers Setup Guide: Step-by-Step for Teams

Devcontainers Setup Guide: Step-by-Step for Teams

What Are Devcontainers?

Devcontainers use Docker to provide isolated, reproducible development environments. Rather than asking each team member to install specific tools, languages, and dependencies on their local machine, you define everything your project needs in a few configuration files that live in your repository.

Dev containers solve the "it works on my machine" problem by defining your entire development environment as code. Every team member gets identical tooling, extensions, and runtime—no more setup documentation that's always out of date. Once the .devcontainer folder is committed to the repo, the environment becomes part of the codebase, not a wiki page.

Prerequisites and Setup

Before you start, you'll need three core components:

1. Docker

Docker is needed to create and manage your containers. Download and install Docker Desktop, or an alternative Docker option, like Docker on a remote host or Docker compliant CLI. Run the Docker Desktop application to start Docker. You will know it's running if you look in the activity tray and see the Docker whale icon.

2. Visual Studio Code

You need Visual Studio Code installed on your machine.

3. Dev Containers Extension

Install and enable the Dev Containers extension of VS Code provided by Microsoft. You can find it in the VS Code Extensions marketplace or install it from the command line.

Creating Your First Devcontainer

The easiest way to get started is to let VS Code generate the initial configuration for you.

Step 1: Open Your Project

Open your project folder in VS Code and open the Command Palette by pressing Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS).

Step 2: Generate Configuration

In the Command Palette, type and select: Dev Containers: Add Dev Container Configuration Files... VS Code will present a list of predefined environment templates.

You can create devcontainer.json either from scratch or by using this command. With this approach, you can pick a pre-defined container configuration from a list. Choose the one that matches your project's primary technology stack—Node.js, Python, .NET, Go, or others.

Step 3: Select Base Image and Features

VS Code walks you through a wizard. Choose the template that matches your project: For a Python project, you'd select Python; for Node.js, you'd select Node.js & TypeScript. You can then choose your specific version.

VS Code generates a `.devcontainer` folder in your project root containing two key files:

  • devcontainer.json: Tells VS Code how to access or create a development container with a well-defined tool and runtime stack.
  • Dockerfile (optional): Defines custom tools beyond the base image.

Understanding the devcontainer.json File

The devcontainer.json file contains metadata and settings required to configure a development container for a given tool and runtime stack. It can be used by tools and services that support the dev container spec to create a development environment that contains one or more development containers.

A basic configuration looks like this:

{
  "name": "Node.js & TypeScript",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm",
  "forwardPorts": [3000],
  "postCreateCommand": "npm install",
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "ms-vscode.vscode-typescript-next"
      ]
    }
  }
}

Key properties:

  • name: Display name for your container
  • image: The base Docker image to use (from Microsoft's official registry)
  • forwardPorts: Makes the port appear as if it's on localhost, which is more secure and works with applications that only listen on localhost.
  • postCreateCommand: Runs commands after container creation (e.g., npm install, pip install -r requirements.txt).
  • customizations: Configure VS Code-specific settings

Installing Extensions Automatically

One of devcontainers' most powerful features is automatic extension installation. The customizations.extensions property lets you define which extensions should be automatically installed as part of the dev container. This is typically just an array of the specific extension IDs that should be retrieved from the public gallery.

Within the `customizations.vscode` section, add your team's essential tools:

"customizations": {
  "vscode": {
    "extensions": [
      "ms-python.python",
      "ms-python.vscode-pylance",
      "ms-python.black-formatter"
    ]
  }
}

Tools like linters are good to standardize on and should be included in your devcontainer.json file. However, personal preferences like UI decorators or themes should not be included.

Using Docker Compose for Multi-Service Environments

For projects that require a database, cache, or other services, use Docker Compose instead of a single image.

The setup lives in a .devcontainer folder at the root of your project, usually containing:

  • devcontainer.json: The main config file. It points to a base image or Dockerfile, lists which VS Code extensions should be installed, sets environment variables, forwards ports, and can run setup commands after the container builds.
  • Dockerfile (optional): If you need something more custom than an off-the-shelf base image.
  • docker-compose.yml (optional): Useful if your dev environment needs multiple services, like a database alongside your app.

A multi-service devcontainer.json references the compose file:

{
  "name": "Full Stack",
  "dockerComposeFile": "docker-compose.yml",
  "service": "app",
  "workspaceFolder": "/workspace"
}

Best Practices for Team Environments

Commit to Version Control

Include your .devcontainer folder in your version control system. This ensures that everyone on your team can access the same configuration and changes to it are tracked. This is critical—your development environment is now part of your codebase.

Keep It Lean

Only include tools and dependencies you actually need. Don't make it overly complex. A bloated container slows down builds and startup times.

Add Documentation

When creating your devcontainer.json configuration file, add comments so that others can understand the setup and stay informed of any changes to it.

Enable Team Collaboration

Using standardized containers reduces discrepancies arising from different tools. With version upgrades, simply updating your devcontainer files ensures the entire team operates on the correct version. When you update the container configuration, all team members receive the change automatically on their next pull.

Optimize Performance

Containers can sometimes introduce performance overhead, particularly on systems with limited resources. Optimize your Docker settings and ensure that your base image is lightweight.

Opening and Rebuilding Your Container

First Time Setup

Load VS Code, and it should ask you to re-open the project in a container if it finds the .devcontainer folder. If not, you can open the Command Palette and run Remote-Containers: Rebuild and Reopen in Container.

The first time you do this, it may take a while as it needs to build the Docker image. After the first load, each time you open the project, it should be much quicker—unless you change the Dockerfile.

Editing Configuration

Since rebuilding a container will reset it to its starting contents (with the exception of your local source code), VS Code does not automatically rebuild if you edit a container configuration file (devcontainer.json, Dockerfile, and docker-compose.yml). When you modify the configuration, use the Dev Containers: Rebuild and Reopen in Container command to apply changes.

The Team Impact

Beyond the advantages of having your team use a consistent environment and tool-chain, this also makes it easier for new contributors or team members to be productive quickly. First-time contributors will require less guidance and hit fewer issues related to environment setup.

Once your `.devcontainer` folder is in your repository, new team members clone the repo, open it in VS Code, and they're prompted to reopen in the container. Within minutes—not hours or days—they have a fully functional development environment with all dependencies installed and all extensions configured.

Next Steps

Start with a simple project to get comfortable with the workflow. Add your team's essential linters, formatters, and debugging tools. Document any custom configuration in comments. As you standardize on devcontainers across your projects, you'll see consistent improvements in onboarding speed, fewer environment-related bugs, and stronger team collaboration.

Dev containers shift local development from fragile, machine-specific setups to reproducible, version-controlled environments. For any team working across different operating systems or managing multiple projects, they're worth the initial setup investment.