feat: Add Docker Compose for simplified local development environment

[doughayden]

Developer Experience Enhancement

Add Docker Compose configuration to simplify local development environment setup and provide consistent development experience across different machines.

Level of Effort: 🟡 Medium (2-3 days)

• Docker Compose setup: 1 day for service configuration and networking
• Development tooling: 1 day for hot reload, debugging, and volume mounts
• Documentation: 0.5 day for setup instructions and troubleshooting
• Testing: 0.5 day for validation across different environments

Current Local Development Setup

What developers need to do now:

1. Install Poetry and dependencies
2. Configure Google Cloud credentials manually
3. Set up environment variables via scripts
4. Run OAuth setup and secrets generation
5. Start backend and frontend services separately
6. Manage port conflicts and service coordination

Pain points:

• Complex initial setup for new developers
• Environment inconsistencies between machines
• Manual service coordination
• Credential and secrets management complexity

Proposed Docker Compose Solution

1. Complete Development Stack

docker-compose.dev.yml:

version: '3.8'

services:
  answer-app:
    build:
      context: .
      dockerfile: src/answer_app/Dockerfile
      target: development
    ports:
      - "8888:8080"
    environment:
      - GOOGLE_CLOUD_PROJECT=${PROJECT}
      - LOG_LEVEL=DEBUG
    volumes:
      - ./src/answer_app:/app/src/answer_app:ro
      - ~/.config/gcloud:/root/.config/gcloud:ro
    command: uvicorn main:app --host 0.0.0.0 --port 8080 --reload
    
  client:
    build:
      context: .
      dockerfile: src/client/Dockerfile
      target: development
    ports:
      - "8080:8080"
    environment:
      - GOOGLE_CLOUD_PROJECT=${PROJECT}
      - LOG_LEVEL=DEBUG
      - TF_VAR_terraform_service_account=${TF_VAR_terraform_service_account}
    volumes:
      - ./src/client:/app/src/client:ro
      - ./.streamlit:/app/.streamlit:ro
    depends_on:
      - answer-app
    command: streamlit run streamlit_app.py --server.port 8080 --server.address 0.0.0.0
    
  # Optional: Local development utilities
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    profiles:
      - cache
      - full

2. Development-Optimized Dockerfiles

Multi-stage Dockerfile for development:

# src/answer_app/Dockerfile
FROM python:3.13-slim as base
# ... base setup

FROM base as development
# Development-specific packages
RUN pip install debugpy ipdb
# Hot reload support
COPY requirements-dev.txt .
RUN pip install -r requirements-dev.txt
# Development command with hot reload
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080", "--reload"]

FROM base as production
# Production optimization
# ... existing production setup

3. Simple Development Commands

Makefile for common operations:

# Makefile
.PHONY: dev-up dev-down dev-logs dev-shell

dev-up:
	docker-compose -f docker-compose.dev.yml up -d
	@echo "Services available at:"
	@echo "  Frontend: http://localhost:8080"
	@echo "  Backend:  http://localhost:8888"
	@echo "  Backend docs: http://localhost:8888/docs"

dev-down:
	docker-compose -f docker-compose.dev.yml down

dev-logs:
	docker-compose -f docker-compose.dev.yml logs -f

dev-shell-backend:
	docker-compose -f docker-compose.dev.yml exec answer-app /bin/bash

dev-shell-frontend:
	docker-compose -f docker-compose.dev.yml exec client /bin/bash

dev-test:
	docker-compose -f docker-compose.dev.yml exec answer-app poetry run pytest

4. Environment Configuration

.env.development:

# .env.development
PROJECT=your-dev-project
TF_VAR_terraform_service_account=dev-sa@your-project.iam.gserviceaccount.com
LOG_LEVEL=DEBUG
GOOGLE_CLOUD_PROJECT=${PROJECT}

# Optional: Redis for caching
REDIS_URL=redis://redis:6379/0

Benefits of Docker Compose Setup

Developer Experience:

• One-command startup: make dev-up starts entire stack
• Consistent environment: Same setup across all developer machines
• Isolated dependencies: No conflicts with local Python installations
• Easy cleanup: make dev-down removes everything

Development Features:

• Hot reload: Code changes automatically reflected
• Debug support: Easy to attach debuggers
• Log aggregation: Centralized logging with docker-compose logs
• Service networking: Automatic service discovery between containers

New Developer Onboarding:

1. Clone repository
2. Run cp .env.example .env.development and configure
3. Run make dev-up
4. Access applications at localhost ports

Implementation Areas

New Files:

• docker-compose.dev.yml: Development stack configuration
• docker-compose.override.yml: Local development overrides
• .env.development: Development environment template
• Makefile: Common development commands
• docs/development/docker-compose.md: Docker Compose development guide

Enhanced Dockerfiles:

• src/answer_app/Dockerfile: Multi-stage with development target
• src/client/Dockerfile: Multi-stage with development target

Documentation Updates:

• docs/development/development.md: Add Docker Compose section
• README.md: Quick start with Docker Compose option

Optional Enhancements

Development Services:

# Additional services for full development stack
services:
  mailhog:
    image: mailhog/mailhog
    ports:
      - "8025:8025"  # Web UI
      - "1025:1025"  # SMTP
    profiles: [full]
    
  adminer:
    image: adminer
    ports:
      - "8081:8080"
    profiles: [full]

IDE Integration:

• VSCode devcontainer configuration
• PyCharm Docker integration
• Debug configuration templates

Testing Strategy

Cross-Platform Testing:

• macOS development environment
• Linux development environment
• Windows development environment (WSL2)

Functionality Testing:

• Service startup and networking
• Hot reload functionality
• Volume mount persistence
• Environment variable propagation

Acceptance Criteria

• Docker Compose configuration for complete development stack
• Hot reload working for both backend and frontend
• Simple make commands for common operations
• Documentation for Docker Compose development workflow
• Cross-platform compatibility (macOS, Linux, Windows/WSL2)
• Proper volume mounts for development files
• Environment variable management
• Service networking between containers

Priority

Low - Nice-to-have improvement for developer experience, but current setup works adequately.

When to Implement

This becomes more valuable when:

• Team size grows beyond 2-3 developers
• New developer onboarding becomes frequent
• Environment setup issues cause productivity loss
• Development environment consistency becomes important
• Complex local service dependencies are added