local-dev-orchestration

name	local-dev-orchestration
description	Local development environment orchestration with Docker Compose, Tilt, and mise for multi-service Python/TS stacks
triggers	["local dev","docker compose","development environment","tilt","mise","devbox"]

Local Development Orchestration

Orchestrate local development environments for multi-service architectures. Covers Docker Compose, Tilt, mise, and service dependency management tailored for Python/TypeScript stacks on macOS ARM64.

Core Principles

1. Fast feedback loops -- hot-reload everything, minimize container rebuilds
2. Production parity -- local env should mirror production as closely as possible
3. One-command startup -- just up or tilt up should bring everything online
4. Isolated dependencies -- each service owns its runtime version via mise

Docker Compose Patterns

Multi-stage development compose

# docker/docker-compose.yml
services:
  api:
    build:
      context: ..
      dockerfile: docker/Dockerfile
      target: development
    volumes:
      - ../src:/app/src:cached
      - ../tests:/app/tests:cached
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://jarvis:jarvis@db:5432/jarvis
      - REDIS_URL=redis://redis:6379/0
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    command: uvicorn jarvis.api.main:app --reload --host 0.0.0.0

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: jarvis
      POSTGRES_USER: jarvis
      POSTGRES_PASSWORD: jarvis
    volumes:
      - pgdata:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U jarvis"]
      interval: 5s
      timeout: 3s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  pgdata:

Dockerfile with multi-stage build

# Base stage
FROM python:3.10-slim AS base
WORKDIR /app
RUN pip install --no-cache-dir uv

# Development stage (includes dev deps, hot reload)
FROM base AS development
COPY pyproject.toml requirements*.txt ./
RUN uv pip install --system -r requirements.txt -r requirements-dev.txt
COPY src/ ./src/
COPY tests/ ./tests/

# Production stage (minimal, no dev deps)
FROM base AS production
COPY pyproject.toml requirements.txt ./
RUN uv pip install --system -r requirements.txt --no-dev
COPY src/ ./src/
RUN useradd --create-home appuser
USER appuser
CMD ["uvicorn", "jarvis.api.main:app", "--host", "0.0.0.0"]

mise Integration

# .mise.toml at project root
[tools]
python = "3.10"
node = "22"
terraform = "1.10"

[env]
PYTHONDONTWRITEBYTECODE = "1"
DATABASE_URL = "postgresql://jarvis:jarvis@localhost:5432/jarvis"
REDIS_URL = "redis://localhost:6379/0"

Run mise install to set up all runtimes. Run mise trust in a new project.

Service Health Checks

Always verify services before running tests or starting dependent services:

# justfile recipe
wait-for-services:
    @echo "Waiting for PostgreSQL..."
    @until pg_isready -h localhost -p 5432 -U jarvis 2>/dev/null; do sleep 1; done
    @echo "Waiting for Redis..."
    @until redis-cli -h localhost ping 2>/dev/null | grep -q PONG; do sleep 1; done
    @echo "All services ready."

Debugging in Containers

For Python services, enable remote debugging:

# In development, add to entrypoint
import debugpy
debugpy.listen(("0.0.0.0", 5678))

Expose port 5678 in compose and attach VS Code debugger.

Performance Tips for macOS

• Use :cached volume mounts for source code
• Use named volumes (not bind mounts) for database data
• Consider Colima instead of Docker Desktop for lower memory usage
• Use COMPOSE_DOCKER_CLI_BUILD=1 DOCKER_BUILDKIT=1 for faster builds