DevContainer Workflow

Guidelines for setting up and maintaining consistent development environments using DevContainers with Docker, featuring non-root user configurations, environment management, multi-stage builds, and Python-focused patterns.

Quick Start Checklist

Directory Structure

code

project/
├── .devcontainer/
│   ├── devcontainer.json       # Container runtime configuration
│   ├── Dockerfile              # Multi-stage development build
│   ├── .env.example            # Dev-specific config template
│   └── .env                    # Dev-specific config (gitignored)
├── .env.example                # Shared config template (committed)
├── .env                        # Shared config (gitignored)
├── Makefile                    # Development task automation
└── pyproject.toml              # Python project configuration

Container Configuration

Multi-Stage Dockerfile Pattern

Use multi-stage builds to separate development, testing, and production stages:

dockerfile

# Base stage with common dependencies
FROM python:3.14-slim AS base

RUN apt-get update && apt-get install -y --no-install-recommends \
    bash \
    curl \
    git \
    make \
    zsh \
    zsh-autosuggestions \
    zsh-syntax-highlighting \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Development stage with full tooling
FROM base AS development

ARG USERNAME=vscode
ARG USER_UID=1000
ARG USER_GID=$USER_UID

# Create non-root user
RUN groupadd --gid $USER_GID $USERNAME && \
    useradd --uid $USER_UID --gid $USER_GID -m $USERNAME -s /bin/zsh && \
    apt-get update && apt-get install -y --no-install-recommends \
    sudo \
    vim \
    && rm -rf /var/lib/apt/lists/* && \
    echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME && \
    chmod 0440 /etc/sudoers.d/$USERNAME

# Install uv
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

WORKDIR /workspace
USER $USERNAME

# Configure shell
RUN echo 'source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh' >> ~/.zshrc && \
    echo 'source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh' >> ~/.zshrc && \
    echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc

# Production stage (minimal footprint)
FROM base AS production

RUN useradd --create-home --shell /bin/bash appuser

WORKDIR /app
USER appuser

COPY --from=development /workspace /app
RUN /app/.venv/bin/pip install --no-cache-dir -e .

Python 3.14+ with UV Installation

Ensure uv is installed in development stage:

dockerfile

# Install uv package manager
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

# (Later in USER vscode section)
# Copy project files for dependency installation
COPY --chown=vscode:vscode pyproject.toml uv.lock* ./
RUN uv sync --no-dev || uv sync

Non-Root User Configuration

User Setup in Dockerfile

Always use a non-root user for security. Standard name is vscode:

dockerfile

ARG USERNAME=vscode
ARG USER_UID=1000
ARG USER_GID=$USER_UID

# Create user with home directory and shell
RUN groupadd --gid $USER_GID $USERNAME && \
    useradd --uid $USER_UID --gid $USER_GID -m $USERNAME -s /bin/zsh && \
    apt-get update && apt-get install -y --no-install-recommends sudo && \
    echo $USERNAME ALL=\(root\) NOPASSWD:ALL > /etc/sudoers.d/$USERNAME && \
    chmod 0440 /etc/sudoers.d/$USERNAME && \
    rm -rf /var/lib/apt/lists/*

# Set user for all subsequent commands
USER $USERNAME

Permissions for Mounted Volumes

Ensure proper ownership of workspace and home directories:

dockerfile

# After copying project files
COPY --chown=vscode:vscode . /workspace

# Ensure workspace permissions
RUN mkdir -p /workspace && chown -R vscode:vscode /workspace

devcontainer.json User Configuration

json

{
  "remoteUser": "vscode"
}

Environment Management

.env File Strategy

Use multiple .env files for different scopes:

•Project root .env - Shared across all environments (gitignored)
•.devcontainer/.env - Development-specific overrides (gitignored)
•.env.example - Template for shared config (committed)
•.devcontainer/.env.example - Template for dev config (committed)

Root `.env.example`

bash

# Shared configuration (safe for version control)
PROJECT_NAME=my-project
LOG_LEVEL=info
PYTHON_VERSION=3.14
DEBUG=false

.devcontainer/.env.example

bash

# Development-specific settings
DEBUG=true
LOG_LEVEL=debug
PYTHONUNBUFFERED=1
HOT_RELOAD=true

Loading Environment in devcontainer.json

json

{
  "runArgs": [
    "--env-file", "${localWorkspaceFolder}/.env",
    "--env-file", "${localWorkspaceFolder}/.devcontainer/.env"
  ]
}

Order matters: later files override earlier ones. Local .devcontainer/.env overrides shared .env.

Docker-in-Docker Support

When to Use

•Building Docker images within the devcontainer
•Running integration tests with containers
•Testing Docker Compose configurations
•Local CI/CD pipeline simulation

Configuration

Add Docker-in-Docker feature to devcontainer.json:

json

{
  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "moby": true
    }
  },
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ]
}

Security Considerations

Mounting the Docker socket grants the container full Docker daemon access:

•Use only in trusted development environments
•Never use in untrusted code environments
•Ensure user in container is trusted
•Consider using Docker contexts for isolation if running sensitive containers

Testing with Docker Compose

makefile

.PHONY: test-integration
test-integration:
	docker compose -f docker-compose.test.yml up -d
	uv run pytest tests/integration/ -v --tb=short
	docker compose -f docker-compose.test.yml down

.PHONY: build-image
build-image:
	docker build -t my-app:latest --target production .

Development Tools

Shell: Zsh Configuration

Configure zsh with plugins for better development experience:

dockerfile

RUN apt-get update && apt-get install -y --no-install-recommends \
    zsh \
    zsh-autosuggestions \
    zsh-syntax-highlighting \
    && rm -rf /var/lib/apt/lists/*

USER vscode
RUN echo 'source /usr/share/zsh/plugins/zsh-autosuggestions/zsh-autosuggestions.zsh' >> ~/.zshrc && \
    echo 'source /usr/share/zsh/plugins/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh' >> ~/.zshrc && \
    echo 'setopt HIST_FIND_NO_DUPS' >> ~/.zshrc && \
    echo 'setopt SHARE_HISTORY' >> ~/.zshrc

VS Code Extensions

Configure recommended extensions in devcontainer.json:

json

{
  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "ms-python.black-formatter",
        "charliermarsh.ruff",
        "ms-azuretools.vscode-docker",
        "eamodio.gitlens",
        "ms-vscode.makefile-tools",
        "GitHub.copilot"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "python.linting.enabled": true,
        "python.formatting.provider": "black",
        "[python]": {
          "editor.defaultFormatter": "ms-python.black-formatter",
          "editor.formatOnSave": true,
          "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
          }
        },
        "editor.formatOnSave": true,
        "files.trimTrailingWhitespace": true,
        "files.insertFinalNewline": true,
        "terminal.integrated.defaultProfile.linux": "zsh"
      }
    }
  }
}

Essential Development Tools

Include in Dockerfile for all development environments:

dockerfile

RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential \
    git \
    curl \
    wget \
    jq \
    && rm -rf /var/lib/apt/lists/*

Volume Mounts

Home Directory Persistence

Preserve shell history, configurations, and VS Code data across container rebuilds:

json

{
  "mounts": [
    "source=${localWorkspaceFolderBasename}-home,target=/home/vscode,type=volume"
  ]
}

Benefits of dynamic naming with ${localWorkspaceFolderBasename}:

•Unique volume per workspace (supports multiple projects)
•Prevents conflicts with other projects
•Clear naming: project-name-home

SSH Key Access

Enable git operations and remote access with SSH keys:

json

{
  "mounts": [
    "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,readonly"
  ]
}

On Windows, use:

json

{
  "mounts": [
    "source=${localEnv:USERPROFILE}\\.ssh,target=/home/vscode/.ssh,type=bind,readonly"
  ]
}

Configure SSH for git:

bash

# In devcontainer or post-create
ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts 2>/dev/null
git config --global core.sshCommand "ssh -i ~/.ssh/id_rsa"

Docker Socket for DinD

json

{
  "mounts": [
    "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
  ]
}

Add user to docker group in container:

dockerfile

RUN groupadd docker || true && \
    usermod -aG docker vscode

Post-Create Commands

Makefile-Driven Initialization

Use postCreateCommand to invoke a Makefile target:

json

{
  "postCreateCommand": "make initialize"
}

Makefile Example

makefile

.PHONY: initialize
initialize: deps env-setup
	@echo "Development environment initialized"

.PHONY: deps
deps:
	@echo "Installing dependencies with uv..."
	uv sync --extra dev

.PHONY: env-setup
env-setup:
	@echo "Setting up environment..."
	mkdir -p logs tmp .cache
	test -f .env || cp .env.example .env
	test -f .devcontainer/.env || cp .devcontainer/.env.example .devcontainer/.env
	@echo ".env files created from templates"

.PHONY: hooks
hooks:
	@echo "Setting up git hooks..."
	pre-commit install || true

.PHONY: clean
clean:
	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
	find . -type f -name "*.pyc" -delete
	rm -rf .pytest_cache htmlcov .coverage .mypy_cache
	uv pip cache prune

.PHONY: test
test:
	uv run pytest tests/ -v --tb=short

.PHONY: check
check:
	uv run pytest tests/ -v
	uv run ruff check .
	uv run mypy src/ --ignore-missing-imports

.PHONY: run
run:
	uv run python -m myapp.cli

Complete devcontainer.json Example

json

{
  "name": "Python Development Environment",
  "description": "Development container with Python 3.14, uv, and Docker-in-Docker",
  "image": "mcr.microsoft.com/devcontainers/python:3.14",
  "dockerFile": "../Dockerfile",
  "target": "development",
  "context": "..",

  "runArgs": [
    "--env-file", "${localWorkspaceFolder}/.env",
    "--env-file", "${localWorkspaceFolder}/.devcontainer/.env"
  ],

  "features": {
    "ghcr.io/devcontainers/features/docker-in-docker:2": {
      "version": "latest",
      "moby": true
    }
  },

  "mounts": [
    "source=${localWorkspaceFolderBasename}-home,target=/home/vscode,type=volume",
    "source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,readonly"
  ],

  "customizations": {
    "vscode": {
      "extensions": [
        "ms-python.python",
        "ms-python.vscode-pylance",
        "ms-python.black-formatter",
        "charliermarsh.ruff",
        "ms-azuretools.vscode-docker",
        "eamodio.gitlens",
        "ms-vscode.makefile-tools"
      ],
      "settings": {
        "python.defaultInterpreterPath": "/usr/local/bin/python",
        "python.linting.enabled": true,
        "python.formatting.provider": "black",
        "[python]": {
          "editor.defaultFormatter": "ms-python.black-formatter",
          "editor.formatOnSave": true,
          "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
          }
        },
        "editor.formatOnSave": true,
        "files.trimTrailingWhitespace": true,
        "files.insertFinalNewline": true,
        "terminal.integrated.defaultProfile.linux": "zsh",
        "terminal.integrated.profiles.linux": {
          "zsh": {
            "path": "/bin/zsh",
            "args": ["-l"]
          }
        }
      }
    }
  },

  "postCreateCommand": "make initialize",
  "postStartCommand": "git config --global --add safe.directory /workspace",

  "remoteUser": "vscode",
  "remoteEnv": {
    "PATH": "/home/vscode/.local/bin:${containerEnv:PATH}"
  }
}

Python with UV Patterns

Project Setup with uv

Initialize project with uv and modern Python:

bash

# In container or locally
uv new my-project --python 3.14
cd my-project
uv sync

Dependencies Management

bash

# Add production dependency
uv add requests fastapi

# Add development dependency
uv add --group dev pytest pytest-cov black ruff mypy

# Add optional group
uv add --group notebook jupyter ipykernel

# Sync all dependencies
uv sync --extra dev

# Run with uv
uv run python -m myapp.cli
uv run pytest tests/ -v

pyproject.toml Structure for Development

toml

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.14"
dependencies = [
    "fastapi>=0.104.0",
    "requests>=2.31.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.4.0",
    "pytest-cov>=4.1.0",
    "black>=23.9.0",
    "ruff>=0.10.0",
    "mypy>=1.5.0",
    "pre-commit>=3.3.0",
]

[tool.uv]
dev-dependencies = ["pytest", "black", "ruff", "mypy"]

[tool.black]
line-length = 88
target-version = ["py314"]

[tool.ruff]
line-length = 88
target-version = "py314"

[tool.mypy]
python_version = "3.14"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = false

Makefile UV Integration

makefile

.PHONY: install
install:
	uv sync --extra dev

.PHONY: test
test:
	uv run pytest tests/ -v --cov=src --cov-report=term-missing

.PHONY: lint
lint:
	uv run ruff check src/ tests/
	uv run mypy src/

.PHONY: format
format:
	uv run black src/ tests/
	uv run ruff check --fix src/ tests/

.PHONY: run
run:
	uv run python -m myapp.cli

Installing from Dockerfile During Build

dockerfile

COPY --chown=vscode:vscode pyproject.toml uv.lock* ./
RUN if [ -f uv.lock ]; then \
      uv sync --no-dev; \
    else \
      uv sync; \
    fi

Testing Support

Unit Testing with pytest

Configure pytest in pyproject.toml:

toml

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_classes = ["Test*"]
python_functions = ["test_*"]
addopts = "-v --tb=short --strict-markers"
markers = [
    "unit: unit tests",
    "integration: integration tests",
    "slow: slow tests",
]

Integration Testing with Docker Compose

Create docker-compose.test.yml:

yaml

version: '3.8'
services:
  postgres:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: testpass
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

Test Makefile Targets

makefile

.PHONY: test test-unit test-integration test-all
test: test-unit

test-unit:
	uv run pytest tests/unit/ -v -m "not slow"

test-integration:
	docker compose -f docker-compose.test.yml up -d
	uv run pytest tests/integration/ -v || true
	docker compose -f docker-compose.test.yml down

test-all:
	uv run pytest tests/ -v --cov=src --cov-report=html

test-watch:
	uv run pytest-watch tests/unit/

Troubleshooting

Permission Denied Errors

Problem: Files owned by root, cannot write from vscode user.

Solution in Dockerfile:

dockerfile

RUN chown -R vscode:vscode /workspace /home/vscode

Check in container:

bash

whoami
ls -la /workspace
ls -la /home/vscode

Extensions Not Installing

Problem: VS Code extensions fail to install in container.

Solution: Use full extension IDs with version pins:

json

{
  "extensions": [
    "ms-python.python@2024.0.0",
    "ms-python.vscode-pylance@2024.0.0"
  ]
}

Or rebuild container:

bash

# In VS Code: Dev Containers: Rebuild Container

Environment Variables Not Loading

Problem: .env files created but variables not available in container.

Solution: Verify files exist and rebuild:

bash

# Check in container
printenv | grep YOUR_VAR
cat /home/vscode/.env

# Rebuild container

Ensure runArgs correctly references env files in devcontainer.json.

Docker Socket Permission Issues

Problem: Cannot access Docker socket from container.

Solution in Dockerfile:

dockerfile

RUN groupadd docker || true && \
    usermod -aG docker vscode

In devcontainer.json:

json

{
  "postCreateCommand": "newgrp docker"
}

UV Cache Issues

Problem: Dependency resolution slow or caching issues.

Solution:

bash

# Clear uv cache in container
uv pip cache prune

# In Dockerfile, use specific versions
RUN uv sync --frozen  # Use uv.lock if available

Volume Mount Issues on Windows

Problem: Volume mounts not working on Windows with WSL2.

Solution: Ensure Docker Desktop WSL2 integration enabled:

bash

# In devcontainer.json, use Windows paths correctly
"mounts": [
  "source=${localEnv:USERPROFILE}\\.ssh,target=/home/vscode/.ssh,type=bind,readonly"
]

Validation Guidance

Pre-Build Validation

Check before building container:

bash

# Validate JSON syntax
python -m json.tool .devcontainer/devcontainer.json

# Check file references
ls -la Dockerfile pyproject.toml .env.example

# Validate Makefile
make --dry-run initialize

Post-Build Validation

After container builds:

bash

# Verify user and permissions
docker exec <container> whoami
docker exec <container> ls -la /workspace

# Test uv installation
docker exec <container> uv --version

# Verify zsh and plugins
docker exec <container> zsh -c "echo $ZSH_VERSION"

# Check VS Code extensions installed
docker exec <container> code --list-extensions 2>/dev/null || echo "VS Code not in container"

Development Environment Check

makefile

.PHONY: validate
validate: validate-files validate-container validate-tools

.PHONY: validate-files
validate-files:
	@echo "Validating devcontainer configuration..."
	@python -m json.tool .devcontainer/devcontainer.json > /dev/null
	@test -f Dockerfile && echo "✓ Dockerfile found" || exit 1
	@test -f pyproject.toml && echo "✓ pyproject.toml found" || exit 1
	@test -f .env.example && echo "✓ .env.example found" || exit 1

.PHONY: validate-container
validate-container:
	@echo "Validating container setup..."
	@whoami | grep -q vscode && echo "✓ Running as vscode user" || exit 1
	@test -d /workspace && echo "✓ Workspace mounted" || exit 1
	@test -d /home/vscode && echo "✓ Home directory mounted" || exit 1

.PHONY: validate-tools
validate-tools:
	@echo "Validating development tools..."
	@uv --version && echo "✓ uv installed" || exit 1
	@python --version && echo "✓ Python available" || exit 1
	@zsh --version && echo "✓ zsh available" || exit 1
	@git --version && echo "✓ git available" || exit 1

.PHONY: check-env
check-env:
	@echo "Environment variables:"
	@printenv | grep -E '^(PYTHON|DEBUG|LOG_LEVEL|PROJECT_NAME)' || echo "No project vars found"
	@test -f .env && echo "✓ .env file loaded" || echo "⚠ .env file missing"

Best Practices Summary

•Always use non-root user (vscode by default) in containers
•Use dynamic volume naming with ${localWorkspaceFolderBasename}-home for persistence
•Prefer uv for Python dependency management in devcontainers
•Multi-stage builds separate development and production concerns
•Keep Dockerfile minimal - offload setup to Makefile targets
•Environment as configuration - use .env files for settings
•Document all tools - list in VS Code extensions and Dockerfile
•Test container builds - validate before committing devcontainer configs
•SSH access when needed - mount .ssh as readonly for git operations
•DinD with caution - only enable Docker socket when truly needed

DevContainer Workflow

Quick Start Checklist

Directory Structure

Container Configuration

Multi-Stage Dockerfile Pattern

Python 3.14+ with UV Installation

Non-Root User Configuration

User Setup in Dockerfile

Permissions for Mounted Volumes

devcontainer.json User Configuration

Environment Management

.env File Strategy

Root .env.example

.devcontainer/.env.example

Loading Environment in devcontainer.json

Docker-in-Docker Support

When to Use

Configuration

Security Considerations

Testing with Docker Compose

Development Tools

Shell: Zsh Configuration

VS Code Extensions

Essential Development Tools

Volume Mounts

Home Directory Persistence

SSH Key Access

Docker Socket for DinD

Post-Create Commands

Makefile-Driven Initialization

Makefile Example

Complete devcontainer.json Example

Python with UV Patterns

Project Setup with uv

Dependencies Management

pyproject.toml Structure for Development

Makefile UV Integration

Installing from Dockerfile During Build

Testing Support

Unit Testing with pytest

Integration Testing with Docker Compose

Test Makefile Targets

Troubleshooting

Permission Denied Errors

Extensions Not Installing

Environment Variables Not Loading

Docker Socket Permission Issues

UV Cache Issues

Volume Mount Issues on Windows

Validation Guidance

Pre-Build Validation

Post-Build Validation

Development Environment Check

Best Practices Summary

Root `.env.example`