DevContainer configuration for consistent development environments with Docker, multi-stage builds, non-root users, environment management, Docker-in-Docker support, and Python with uv...
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.
.devcontainer/ directory structuredevcontainer.json with runtime settingsDockerfile for development environmentvscode user with proper permissions.env.example templates for configurationpostCreateCommand with Makefile integrationproject/
├── .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
Use multi-stage builds to separate development, testing, and production stages:
# 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 .
Ensure uv is installed in development stage:
# 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
Always use a non-root user for security. Standard name is vscode:
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
Ensure proper ownership of workspace and home directories:
# After copying project files
COPY --chown=vscode:vscode . /workspace
# Ensure workspace permissions
RUN mkdir -p /workspace && chown -R vscode:vscode /workspace
{
"remoteUser": "vscode"
}
Use multiple .env files for different scopes:
.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).env.example# Shared configuration (safe for version control)
PROJECT_NAME=my-project
LOG_LEVEL=info
PYTHON_VERSION=3.14
DEBUG=false
# Development-specific settings
DEBUG=true
LOG_LEVEL=debug
PYTHONUNBUFFERED=1
HOT_RELOAD=true
{
"runArgs": [
"--env-file", "${localWorkspaceFolder}/.env",
"--env-file", "${localWorkspaceFolder}/.devcontainer/.env"
]
}
Order matters: later files override earlier ones. Local .devcontainer/.env overrides shared .env.
Add Docker-in-Docker feature to devcontainer.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"
]
}
Mounting the Docker socket grants the container full Docker daemon access:
.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 .
Configure zsh with plugins for better development experience:
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
Configure recommended extensions in devcontainer.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"
}
}
}
}
Include in Dockerfile for all development environments:
RUN apt-get update && apt-get install -y --no-install-recommends \
build-essential \
git \
curl \
wget \
jq \
&& rm -rf /var/lib/apt/lists/*
Preserve shell history, configurations, and VS Code data across container rebuilds:
{
"mounts": [
"source=${localWorkspaceFolderBasename}-home,target=/home/vscode,type=volume"
]
}
Benefits of dynamic naming with ${localWorkspaceFolderBasename}:
project-name-homeEnable git operations and remote access with SSH keys:
{
"mounts": [
"source=${localEnv:HOME}/.ssh,target=/home/vscode/.ssh,type=bind,readonly"
]
}
On Windows, use:
{
"mounts": [
"source=${localEnv:USERPROFILE}\\.ssh,target=/home/vscode/.ssh,type=bind,readonly"
]
}
Configure SSH for git:
# 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"
{
"mounts": [
"source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind"
]
}
Add user to docker group in container:
RUN groupadd docker || true && \
usermod -aG docker vscode
Use postCreateCommand to invoke a Makefile target:
{
"postCreateCommand": "make initialize"
}
.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
{
"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}"
}
}
Initialize project with uv and modern Python:
# In container or locally
uv new my-project --python 3.14
cd my-project
uv sync
# 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
[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
.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
COPY --chown=vscode:vscode pyproject.toml uv.lock* ./
RUN if [ -f uv.lock ]; then \
uv sync --no-dev; \
else \
uv sync; \
fi
Configure pytest in pyproject.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",
]
Create docker-compose.test.yml:
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
.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/
Problem: Files owned by root, cannot write from vscode user.
Solution in Dockerfile:
RUN chown -R vscode:vscode /workspace /home/vscode
Check in container:
whoami
ls -la /workspace
ls -la /home/vscode
Problem: VS Code extensions fail to install in container.
Solution: Use full extension IDs with version pins:
{
"extensions": [
"ms-python.python@2024.0.0",
"ms-python.vscode-pylance@2024.0.0"
]
}
Or rebuild container:
# In VS Code: Dev Containers: Rebuild Container
Problem: .env files created but variables not available in container.
Solution: Verify files exist and rebuild:
# Check in container
printenv | grep YOUR_VAR
cat /home/vscode/.env
# Rebuild container
Ensure runArgs correctly references env files in devcontainer.json.
Problem: Cannot access Docker socket from container.
Solution in Dockerfile:
RUN groupadd docker || true && \
usermod -aG docker vscode
In devcontainer.json:
{
"postCreateCommand": "newgrp docker"
}
Problem: Dependency resolution slow or caching issues.
Solution:
# Clear uv cache in container
uv pip cache prune
# In Dockerfile, use specific versions
RUN uv sync --frozen # Use uv.lock if available
Problem: Volume mounts not working on Windows with WSL2.
Solution: Ensure Docker Desktop WSL2 integration enabled:
# In devcontainer.json, use Windows paths correctly
"mounts": [
"source=${localEnv:USERPROFILE}\\.ssh,target=/home/vscode/.ssh,type=bind,readonly"
]
Check before building container:
# 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
After container builds:
# 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"
.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"
vscode by default) in containers${localWorkspaceFolderBasename}-home for persistence.env files for settings.ssh as readonly for git operations
