docker-compose.yml

# Copy .env.example to .env and fill in your values before running.
# cp .env.example .env

services:

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    ports:
      - "5432:5432"  # Uncomment for local debug only — do NOT expose in production
    volumes:
      - postgres_data:/var/lib/postgresql/data
    # Tuning targeted at 2 cores / 5-6 GB RAM dev VM. Measured 2026-05-23:
    # +39% on Python propagator (53s -> 38s at 500x365), +22% on SQL window
    # spike (13.5s -> 11.1s). See docs/SCALABILITY.md "Tier 3 spike".
    # Adjust shared_buffers / effective_cache_size if RAM changes; bump
    # max_parallel_workers* if cores > 4.
    command: >
      postgres
      -c shared_buffers=1GB
      -c work_mem=32MB
      -c maintenance_work_mem=256MB
      -c effective_cache_size=4GB
      -c max_worker_processes=4
      -c max_parallel_workers=2
      -c max_parallel_workers_per_gather=1
      -c jit=off
      -c wal_buffers=16MB
      -c temp_buffers=16MB
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
    # shared_buffers=1GB above is a hard Postgres allocation at startup, plus
    # work_mem/maintenance_work_mem headroom for concurrent queries — the
    # memory limit must clear shared_buffers with margin or Postgres OOMs on
    # boot. 2g matches the "2 cores / 5-6 GB RAM dev VM" target this tuning
    # was benchmarked against (see comment above and docs/SCALABILITY.md).
    deploy:
      resources:
        limits:
          memory: 2g

  api:
    build:
      context: .
      dockerfile: Dockerfile
      # Opt-in Rust kernel wheel (OOTILS_ENGINE=rust availability — the
      # runtime default engine stays 'sql' regardless, see Dockerfile).
      # Default 0 = today's build, no rust: toolchain pulled. Override with
      # `WITH_RUST=1 docker compose build` or a `.env` entry.
      args:
        WITH_RUST: ${WITH_RUST:-0}
    environment:
      DATABASE_URL: postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      OOTILS_API_TOKEN: ${OOTILS_API_TOKEN}
      OOTILS_ENABLE_API_DOCS: ${OOTILS_ENABLE_API_DOCS:-0}
      OOTILS_DB_POOL_MIN_SIZE: ${OOTILS_DB_POOL_MIN_SIZE:-1}
      OOTILS_DB_POOL_MAX_SIZE: ${OOTILS_DB_POOL_MAX_SIZE:-10}
      OOTILS_DB_POOL_TIMEOUT_SECONDS: ${OOTILS_DB_POOL_TIMEOUT_SECONDS:-10}
    ports:
      - "${OOTILS_API_PORT:-8000}:8000"
    depends_on:
      postgres:
        condition: service_healthy
    command: uvicorn ootils_core.api.app:app --host 0.0.0.0 --port 8000
    # Demo-scale FastAPI/uvicorn process (single worker, pool max 10 conns).
    deploy:
      resources:
        limits:
          memory: 512m

volumes:
  postgres_data: