devcontainer-workflow

# 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 - [ ] Create `.devcontainer/` directory structure - [ ] Configure `devcontainer.json` with runtime settings - [ ] Create multi-stage `Dockerfile` for development environment - [ ] Set up non-root `vscode` user with proper permissions - [ ] Configure volume mounts (home, SSH, docker socket) - [ ] Create `.env.example` templates for configuration - [ ] Set up `postCreateCommand` with Makefile integration - [ ] Configure VS Code extensions in customizations - [ ] Test container build and entry - [ ] Verify all development tools are accessible --- ## Directory Structure ``` 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: 1. **Project root `.env`** - Shared across all environments (gitignored) 2. **`.devcontainer/.env`** - Development-specific overrides (gitignored) 3. **`.env.example`** - Template for shared config (committed) 4. **`.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": "..",