DevContainers: How to save setup time for your development team

Setting up a project in modern software development often requires installing precise versions of tools, libraries, and dependencies. For example, a typical setup process might involve installing a specific version of Node.js, configuring a database like PostgreSQL, and ensuring Git and other essential tools are available and properly configured. It’s a process that can take hours or even days, and it’s prone to errors that lead to the dreaded phrase: “It works on my machine!”.

Enter DevContainers — a powerful tool that can transform how development environments are configured and shared. 🚀 In this article, we’ll explore what DevContainers are, what they serve for, how they differ from standard Docker images, and some best practices to make the most of them. Whether you’re a junior developer or a team leader, you’ll learn how DevContainers can save your team time and reduce setup headaches. 🌟

What Are DevContainers?

A DevContainer is a pre-configured, portable development environment that runs inside a Docker container. It includes everything a developer needs to work on a project: tools, libraries, dependencies, and even personal preferences like shell configurations or VS Code extensions. These environments are defined in code, typically using a .devcontainer folder with configuration files. 🛠️

How Do DevContainers Work?

• Developers write a devcontainer.json file, which defines the environment.
• The container is built using Docker, pulling dependencies and tools as specified.
• When opened in a compatible editor like VS Code, JetBrains IDEs, or GitHub Codespaces, the environment is ready to use with all configurations applied. ✅

What Are DevContainers Used For?

1. Consistency Across Environments

Every developer on the team uses the exact same environment, reducing “it works on my machine” issues. This is especially important for projects with complex dependencies or version requirements. 🔒

2. Streamlined Onboarding

New team members can start contributing immediately. Instead of following lengthy setup instructions, they simply install Docker, open the project, and the environment is ready to go. 🚀

3. Isolation of Projects

Each project can have its own isolated environment. For instance, one project can use Node.js 16, while another uses Node.js 18, with no conflicts. 🧳

4. Reproducible Bug Fixing

When bugs are reported, developers can recreate the exact environment where the issue occurred, making debugging more straightforward. 🐞

5. Aligned CI/CD Workflows

By matching local development environments with staging or production environments, DevContainers reduce surprises during deployment. 🔄

How DevContainers Differ from Standard Docker Images

While both DevContainers and Docker images use containers, they serve different purposes:

In essence, DevContainers extend the Docker concept to include the entire development workflow, not just the application runtime. 🛠️

How to Set Up a DevContainer

Setting up a DevContainer involves creating specific configuration files to define your development environment. Here’s a step-by-step guide:

1. Create the .devcontainer Directory

In the root of your project, create a directory named .devcontainer. This folder will contain all configuration files for your DevContainer. 📂

mkdir .devcontainer

2. Define the devcontainer.json File

Inside the .devcontainer directory, create a devcontainer.json file. This file specifies your development environment’s tools, libraries, and settings. A sample file might look like this: ✍️

{
  "name": "My DevContainer",
  "image": "node:16",
  "workspaceFolder": "/home/node/app",
  "customizations": {
    "vscode": {
      "settings": {
        "terminal.integrated.defaultProfile.linux": "zsh"
      },
      "extensions": [
        "dbaeumer.vscode-eslint"
      ]
    }
  },
  "features": {
    "ghcr.io/devcontainers/features/git:1": {},
  },
}

3. (Optional) Create a Dockerfile

For custom environments, add a Dockerfile to the .devcontainer folder. This allows you to define specific dependencies. 🧑‍🍳

FROM node:16
WORKDIR /home/node/app
USER node

If you use this approach, you will also need to edit the devcontainer.json file to substitute the image property with a reference to the Dockerfile. 🔗

{
  "dockerFile": "Dockerfile",
}

4. (Optional) Use a docker-compose.yml File

For more complex setups, use a docker-compose.yml file to orchestrate multiple services. 🔗

version: '3'
services:
  app:
    build:
      context: .
      dockerfile: .devcontainer/Dockerfile
    volumes:
      - .:/home/node/app:cached
    ports:
      - 3000:3000
  db:
    image: postgres:13
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
    ports:
      - 5432:5432

If you use this approach, you will also need to edit the devcontainer.json file to substitute the image property with a reference to the docker-compose.yml file under the dockerComposeFile property and specify the service name under service. 🔗

{
  "dockerComposeFile": [
    "docker-compose.yml"
  ],
  "service": "app"
}

5. Launch the DevContainer

Open the project in VS Code. Use the Command Palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and select Remote-Containers: Reopen in Container. Your environment will build and launch automatically. 🚀

Best Practices for Using DevContainers

1. Use devcontainer.example.json for Flexible Configurations

Create a devcontainer.example.json file with the base setup for your environment. Add the actual devcontainer.json to .gitignore, so developers can customize it without affecting the shared configuration. 📝

Why?

This approach allows developers to tweak their environment (e.g., shell preferences or VS Code extensions) while keeping a consistent base setup for the team. 🔧

.devcontainer
|- .gitignore
|- devcontainer.example.json
|- devcontainer.json (ignored)
|- docker-compose.yml

2. Separate Environments for Different Use Cases

Organize your DevContainer setups into folders for specific environments, such as dev and test. Each can have its own devcontainer.json and docker-compose.yml. 🗂️

Example Use Case:

• Development: Includes tools like an ELK stack for local logs.
• Testing: A minimal setup for CI pipelines, excluding heavy tools. 🛠️

.devcontainer
|- dev
  |- devcontainer.json
  |- docker-compose.yml
|- test
  |- devcontainer.json
  |- docker-compose.yml

3. Modularize with Multiple docker-compose.yml Files

Split your docker-compose.yml into multiple files based on functionality, such as:

• Core application and database.
• Observability tools (e.g., Grafana, Prometheus).
• Admin tools (e.g., PGAdmin). 📚

Why?

Developers can include only the tools they need, saving resources and speeding up container startup. ⏩

How?

Reference the files in devcontainer.json like this:

{
  "dockerComposeFile": [
    "docker-compose.app.yml",
    "docker-compose.observability.yml",
    "docker-compose.tooling.yml"
  ]
}

4. Leverage DevContainer Features for Tooling

DevContainers support additional features for installing common tools, such as AWS CLI, Stripe CLI, Git, Zsh, and other daily-used tools. ⚙️ You can explore the full list of available features at containers.dev/features.

Why?

Instead of manually adding these tools to your Dockerfile, you can declare them in devcontainer.json. For example:

{
  "features": {
    "ghcr.io/devcontainers/features/aws-cli:1": {
      "version": "latest"
    },
    "ghcr.io/nullcoder/devcontainer-features/stripe-cli:1": {}
  }
}

The Benefits of DevContainers for Teams

1. Time Savings: Setting up or switching environments takes seconds, not hours. ⏱️
2. Reduced Friction: Developers can focus on coding instead of debugging setup issues. 🛠️
3. Scalability: DevContainers grow with your team, accommodating custom setups or new tools. 🚀
4. Improved Collaboration: Everyone works in a consistent environment while still having flexibility for personal preferences. 🤝

Conclusion

DevContainers are more than just Docker images for development—they’re a way to make your entire development environment portable, consistent, and easy to use. Whether you’re a junior developer tired of complex setup processes or a team leader looking to streamline workflows, DevContainers can save time, reduce errors, and boost productivity. 💡

Start small by creating a basic devcontainer.json, and as you grow comfortable, explore the best practices outlined here. Your future self (and your team) will thank you for it! 🙌