Stir Trek 2025 and Multiple Dev Containers

This month at Stir Trek 2025, I presented on Dev Containers and GitHub Codespaces, demonstrating how these tools streamline both local and cloud-based development workflows. The session covered the essentials of creating portable development environments, customizing containers with features and extensions, and launching Codespaces directly from your repository. A lively Q&A followed, with attendees asking about strategies for running and working with multiple containers. Below, I’ve distilled those discussions and provided a deeper dive into shared container configurations across multiple projects-including folder structures, Docker Compose setups, VS Code workflows, and advanced tips you can apply in your own work.

Recap: Dev Containers and Codespaces

#

Dev Containers are Docker-based environments enriched with development-specific tooling, settings, and startup tasks as defined in a devcontainer.json file. They enable you to use a container as a full-featured development environment-isolating dependencies, standardizing tool versions, and enabling reproducible setups locally or remotely (Dev Containers).

GitHub Codespaces builds on Dev Containers by providing cloud-hosted environments that spin up in seconds with configurable CPU, memory, and storage. Codespaces leverages the same open specification as Dev Containers, making your devcontainer.json a first-class citizen whether you connect via VS Code, IntelliJ, or directly in the browser (GitHub Docs).

Q&A: Running Multiple Containers

#

Can I connect to multiple containers at once?

#

By default, VS Code allows only one container per window, but you can open additional windows and attach each to a different container to work on multiple services in parallel (Visual Studio Code).

What about using a single window for multiple containers?

#

If you use Docker Compose, define multiple services in your docker-compose.yml and create separate devcontainer.json configurations for each service-each referencing the common Compose file. VS Code will then list each configuration in its Dev Container picker, letting you reopen the current window to connect to a different service without duplicating your Compose setup (Dev Containers).

How do I configure separate containers for multiple projects?

#

To maintain isolation and clarity, place each container configuration in its own subdirectory under .devcontainer, following the pattern .devcontainer/<project>/devcontainer.json. Tools supporting the spec recognize this layout and list all found configurations in the Codespaces or VS Code Dev Container dropdown (containers.dev, GitHub Docs).

Shared .devcontainer Folder Structure

#

Centralize your container configurations in a single root directory:

dev-container/
├─ .devcontainer/
│  ├─ .env
│  ├─ docker-compose.yml
│  ├─ project-a-node-js/
│  │   └─ devcontainer.json
│  ├─ project-b-node-js/
│  │   └─ devcontainer.json
│  ├─ project-c-python/
│  │   └─ devcontainer.json
│  └─ project-d-go-lang/
│       └─ devcontainer.json
├─ project-a-node-js/
├─ project-b-node-js/
├─ project-c-python/
└─ project-d-go-lang/

This layout lets all projects share a single Compose definition and environment variables-reducing duplication and easing updates (containers.dev).

Common Docker Compose File

#

In .devcontainer/docker-compose.yml, define every project service alongside shared dependencies:

services:
  project-a-node-js:
    image: mcr.microsoft.com/devcontainers/base:latest
    volumes:
      - ..:/workspaces:cached
    ports:
      - "8001:8000"
    command: sleep infinity

  project-b-node-js:
    image: mcr.microsoft.com/devcontainers/base:latest
    volumes:
      - ..:/workspaces:cached
    ports:
      - "8002:8000"
    depends_on:
      - postgres

  project-c-python:
    image: mcr.microsoft.com/devcontainers/base:latest
    volumes:
      - ..:/workspaces:cached
    ports:
      - "8003:8000"
    depends_on:
      - postgres

  project-d-go-lang:
    image: mcr.microsoft.com/devcontainers/base:latest
    volumes:
      - ..:/workspaces:cached
    ports:
      - "8004:8000"

  postgres:
    image: postgres:latest
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

Each service listens on port 8000 internally and is mapped to a unique host port (8001-8004) to prevent collisions (Visual Studio Code).

Workspace Mounts & Folder Mapping

#

Mounting the root-level folder into /workspaces in each container gives uniform access to all projects. In each devcontainer.json, point workspaceFolder at the specific subdirectory:

"workspaceFolder": "/workspaces/project-b-node-js"

This ensures your editor is scoped appropriately when connected (Dev Containers).

Per-Project devcontainer.json

#

Each project’s configuration references the shared Compose file and specifies its service:

{
  "name": "Project B Dev Container",
  "dockerComposeFile": ["../docker-compose.yml"],
  "service": "project-b-node-js",
  "workspaceFolder": "/workspaces/project-b-node-js",
  "shutdownAction": "none"
}

Using "shutdownAction": "none" keeps all containers running when you close one window, so you don’t inadvertently tear down shared services (Dev Containers).

Building & Switching Between Containers

#

1. Open the root folder (dev-container/) in VS Code.
2. Reopen in Container: Run Dev Containers: Reopen in Container and select your desired project.
3. Switch Container: Later, use Dev Containers: Switch Container to hop to another project without restarting the Docker stack (Visual Studio Code, GitHub Docs).

Advanced Multi-Project Strategies

#

Environment-Specific Overrides

#

Layer additional Compose files for environment-specific tweaks:

docker-compose -f docker-compose.yml \
  -f docker-compose.override.yml \
  -f docker-compose.dev.yml up -d

Overrides can redefine images, ports, mounts, or feature flags per environment (Visual Studio Code).

Isolated Networks & Namespaces

#

Define separate Docker networks to segment traffic:

networks:
  dev-a: {}
  dev-b: {}

services:
  project-a-node-js:
    networks: [dev-a]
  project-b-node-js:
    networks: [dev-b]
  postgres:
    networks: [dev-a, dev-b]

This prevents unintended inter-service communication between project environments (Visual Studio Code).

GitHub Codespaces Integration

#

Codespaces recognizes the same .devcontainer layout:

• Configuration Dropdown: Multiple devcontainer.json files under .devcontainer/ are automatically listed when creating a Codespace (GitHub Docs).
• Port Forwarding: Host-mapped ports (8001-8004) surface as forwarded ports in the Codespaces UI.
• Pre-builds & Secrets: Enable pre-builds in devcontainer.json and leverage repository or organization secrets instead of a local .env file (The GitHub Blog).

Lifecycle Customization

#

Use Dev Container lifecycle hooks per project to automate setup:

"postCreateCommand": "cd /workspaces/project-a-node-js && npm ci",
"postStartCommand": "npm run migrate",
"initializeCommand": "git submodule update --init"

These commands ensure each container is fully prepared for development immediately (Dev Containers).

Troubleshooting Tips

#

• Stuck at “Rebuilding container…”: Clear the Docker build cache or raise VS Code’s Docker logging level.
• Ports not forwarding: Verify forwardPorts in devcontainer.json or check Codespaces port settings.
• Volume performance issues: On macOS/Windows, consider isolating cache directories (e.g., node_modules) in named volumes to speed up I/O (Some Natalie’s corner of the internet, pamela fox’s blog).

Conclusion

#

By centralizing Dev Container configurations and sharing a unified docker-compose.yml, you eliminate duplication, streamline dependency management, and enable seamless switching between multiple projects-both locally and in GitHub Codespaces. This pattern scales from a handful of services to extensive microservice landscapes, delivering consistent, reproducible developer environments across your entire workspace.