docker-compose.yml

# =============================================================================
# Docker Compose Configuration for Kixi Platform
# =============================================================================
#
# This file defines all services for the Kixi platform:
#   - postgres: PostgreSQL 16 database
#   - backend-api: Spring Boot WebFlux API (Java 17)
#   - ocr-service: FastAPI OCR service with PaddleOCR-VL (Python 3.11)
#
# Usage:
#   docker-compose up --build           # Start all services
#   docker-compose up -d postgres       # Start only database
#   docker-compose up ocr-service       # Start OCR service with dependencies
#   docker-compose logs -f backend-api  # Follow backend logs
#   docker-compose down -v              # Stop and remove volumes
#
# Profiles:
#   docker-compose --profile gpu up     # Start with GPU-enabled OCR
#   docker-compose --profile cache up   # Start with Redis cache
#
# Environment Variables:
#   Copy .env.example to .env and customize as needed
#
# =============================================================================

services:
  # ===========================================================================
  # PostgreSQL Database
  # ===========================================================================
  postgres:
    image: postgres:16-alpine
    container_name: kixi-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-kixi}
      POSTGRES_USER: ${POSTGRES_USER:-kixi}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-kixi_secret}
      PGDATA: /var/lib/postgresql/data/pgdata
    ports:
      - "${POSTGRES_PORT:-5433}:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./services/backend-api/docker/postgres/init.sql:/docker-entrypoint-initdb.d/01-init.sql:z
    healthcheck:
      test:
        [
          "CMD-SHELL",
          "pg_isready -U ${POSTGRES_USER:-kixi} -d ${POSTGRES_DB:-kixi}",
        ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
    networks:
      - kixi-network

  # ===========================================================================
  # Backend API (Spring Boot WebFlux)
  # ===========================================================================
  # Build uses Dockerfile from infra/docker/ with project root as context
  # This allows access to all project files during build
  backend-api:
    build:
      context: .
      dockerfile: infra/docker/backend.Dockerfile
    container_name: kixi-backend-api
    restart: unless-stopped
    environment:
      # Database Configuration
      SPRING_R2DBC_URL: r2dbc:postgresql://postgres:5432/${POSTGRES_DB:-kixi}
      SPRING_R2DBC_USERNAME: ${POSTGRES_USER:-kixi}
      SPRING_R2DBC_PASSWORD: ${POSTGRES_PASSWORD:-kixi_secret}
      # Existing databases created by the legacy init.sql are baselined at V16;
      # fresh databases are empty and run the complete migration chain.
      SPRING_FLYWAY_BASELINE_ON_MIGRATE: ${SPRING_FLYWAY_BASELINE_ON_MIGRATE:-true}
      SPRING_FLYWAY_BASELINE_VERSION: ${SPRING_FLYWAY_BASELINE_VERSION:-16}
      # OCR Service Configuration
      OCR_SERVICE_URL: http://ocr-service:8000
      OCR_SERVICE_TIMEOUT_MS: ${OCR_SERVICE_TIMEOUT_MS:-120000}
      # Application Configuration
      SPRING_PROFILES_ACTIVE: ${SPRING_PROFILE:-docker}
      SERVER_PORT: 8080
      # Logging Configuration
      LOGGING_LEVEL_ROOT: ${LOG_LEVEL:-INFO}
      LOGGING_LEVEL_AO_CREATIVEMODE: ${APP_LOG_LEVEL:-DEBUG}
      # JWT Configuration (required; never use a repository default)
      APP_JWT_SECRET: ${APP_JWT_SECRET:?Set APP_JWT_SECRET to a random value of at least 32 characters}
      APP_JWT_EXPIRATION_MS: ${APP_JWT_EXPIRATION_MS:-86400000}
      APP_AUTH_GOOGLE_STATE_COOKIE_SECURE: ${GOOGLE_OAUTH_STATE_COOKIE_SECURE:-true}
      OCR_SERVICE_API_KEY: ${OCR_API_KEY:?Set OCR_API_KEY for backend-to-OCR authentication}
      # Object storage. Keep local for the default development profile;
      # use STORAGE_PROVIDER=s3 with --profile storage for MinIO.
      STORAGE_PROVIDER: ${STORAGE_PROVIDER:-local}
      STORAGE_LOCAL_ROOT: ${STORAGE_LOCAL_ROOT:-/tmp/kixi/uploads}
      STORAGE_PUBLIC_BASE_URL: ${STORAGE_PUBLIC_BASE_URL:-/uploads}
      STORAGE_S3_ENDPOINT: ${STORAGE_S3_ENDPOINT:-http://minio:9000}
      STORAGE_S3_REGION: ${STORAGE_S3_REGION:-us-east-1}
      STORAGE_S3_BUCKET: ${STORAGE_S3_BUCKET:-kixi-images}
      STORAGE_S3_ACCESS_KEY: ${STORAGE_S3_ACCESS_KEY:-kixi-minio}
      STORAGE_S3_SECRET_KEY: ${STORAGE_S3_SECRET_KEY:-kixi-minio-secret}
      STORAGE_S3_PATH_STYLE_ACCESS: ${STORAGE_S3_PATH_STYLE_ACCESS:-true}
      STORAGE_MAX_OBJECT_SIZE_BYTES: ${STORAGE_MAX_OBJECT_SIZE_BYTES:-20971520}
    ports:
      - "${BACKEND_PORT:-8080}:8080"
    depends_on:
      postgres:
        condition: service_healthy
      ocr-service:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/actuator/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    networks:
      - kixi-network

  # ===========================================================================
  # OCR Service (FastAPI + PaddleOCR-VL)
  # ===========================================================================
  # Build uses Dockerfile from infra/docker/ with project root as context
  # For local development, you can use the Dockerfile in services/ocr-service/
  ocr-service:
    build:
      context: .
      dockerfile: infra/docker/ocr.Dockerfile
      # Alternative: Use local Dockerfile for development
      # context: ./services/ocr-service
      # dockerfile: Dockerfile
    container_name: kixi-ocr-service
    restart: unless-stopped
    environment:
      # Service Configuration
      SERVICE_NAME: ocr-service
      SERVICE_VERSION: 1.0.0
      ENVIRONMENT: ${ENVIRONMENT:-docker}
      DEBUG: ${OCR_DEBUG:-false}
      ENABLE_AUTH: "true"
      API_KEY: ${OCR_API_KEY:?Set OCR_API_KEY for backend-to-OCR authentication}
      CORS_ORIGINS: ${OCR_CORS_ORIGINS:-}
      TRUSTED_PROXY_IPS: ${OCR_TRUSTED_PROXY_IPS:-}
      # Server Configuration
      HOST: 0.0.0.0
      PORT: 8000
      WORKERS: ${OCR_WORKERS:-1}
      # OCR Configuration
      OCR_LANG: ${OCR_LANG:-pt}
      OCR_USE_GPU: ${OCR_USE_GPU:-false}
      OCR_USE_ANGLE_CLS: ${OCR_USE_ANGLE_CLS:-true}
      OCR_SHOW_LOG: ${OCR_SHOW_LOG:-false}
      # Processing Configuration
      MAX_IMAGE_SIZE_MB: ${MAX_IMAGE_SIZE_MB:-20.0}
      MAX_IMAGES_PER_REQUEST: ${MAX_IMAGES_PER_REQUEST:-10}
      PROCESSING_TIMEOUT_SECONDS: ${PROCESSING_TIMEOUT_SECONDS:-120}
      MIN_CONFIDENCE_THRESHOLD: ${MIN_CONFIDENCE_THRESHOLD:-0.5}
      # Preprocessing Configuration
      ENABLE_DESKEW: ${ENABLE_DESKEW:-true}
      ENABLE_DENOISE: ${ENABLE_DENOISE:-true}
      TARGET_DPI: ${TARGET_DPI:-300}
      # Logging Configuration
      LOG_LEVEL: ${OCR_LOG_LEVEL:-INFO}
      LOG_FORMAT: ${OCR_LOG_FORMAT:-json}
      # Metrics Configuration
      ENABLE_METRICS: ${ENABLE_METRICS:-true}
    ports:
      - "${OCR_BIND_ADDRESS:-127.0.0.1}:${OCR_PORT:-8000}:8000"
    volumes:
      # Persist PaddleOCR models between container restarts
      - ocr_models:/home/ocr/.paddleocr
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 60s
    deploy:
      resources:
        limits:
          memory: 4G
        reservations:
          memory: 2G
    networks:
      - kixi-network

  # ===========================================================================
  # OCR Service with GPU Support (Optional Profile)
  # ===========================================================================
  # Start with: docker-compose --profile gpu up
  # Requires NVIDIA Docker runtime and CUDA-compatible GPU
  ocr-service-gpu:
    build:
      context: .
      dockerfile: infra/docker/ocr.Dockerfile
    container_name: kixi-ocr-service-gpu
    profiles:
      - gpu
    restart: unless-stopped
    environment:
      SERVICE_NAME: ocr-service-gpu
      SERVICE_VERSION: 1.0.0
      ENVIRONMENT: ${ENVIRONMENT:-docker}
      DEBUG: ${OCR_DEBUG:-false}
      ENABLE_AUTH: "true"
      API_KEY: ${OCR_API_KEY:?Set OCR_API_KEY for backend-to-OCR authentication}
      CORS_ORIGINS: ${OCR_CORS_ORIGINS:-}
      TRUSTED_PROXY_IPS: ${OCR_TRUSTED_PROXY_IPS:-}
      HOST: 0.0.0.0
      PORT: 8000
      WORKERS: ${OCR_WORKERS:-1}
      # Enable GPU acceleration
      OCR_LANG: ${OCR_LANG:-pt}
      OCR_USE_GPU: "true"
      OCR_USE_ANGLE_CLS: "true"
      OCR_SHOW_LOG: "false"
      MAX_IMAGE_SIZE_MB: "20.0"
      MAX_IMAGES_PER_REQUEST: "10"
      PROCESSING_TIMEOUT_SECONDS: "120"
      MIN_CONFIDENCE_THRESHOLD: "0.5"
      ENABLE_DESKEW: "true"
      ENABLE_DENOISE: "true"
      TARGET_DPI: "300"
      LOG_LEVEL: INFO
      LOG_FORMAT: json
      ENABLE_METRICS: "true"
    ports:
      - "${OCR_GPU_BIND_ADDRESS:-127.0.0.1}:${OCR_GPU_PORT:-8001}:8000"
    volumes:
      - ocr_models_gpu:/home/ocr/.paddleocr
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 120s
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]
    networks:
      - kixi-network

  # ===========================================================================
  # Redis Cache (Optional Profile)
  # ===========================================================================
  # Start with: docker-compose --profile cache up
  # Used for caching OCR results and session management
  redis:
    image: redis:7-alpine
    container_name: kixi-redis
    profiles:
      - cache
    restart: unless-stopped
    command: redis-server --appendonly yes
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 3
    networks:
      - kixi-network

  # ===========================================================================
  # S3-compatible object storage (Optional Profile)
  # ===========================================================================
  # Start with STORAGE_PROVIDER=s3 docker-compose --profile storage up
  minio:
    image: minio/minio:RELEASE.2024-06-13T22-53-53Z
    container_name: kixi-minio
    profiles:
      - storage
    restart: unless-stopped
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: ${STORAGE_S3_ACCESS_KEY:-kixi-minio}
      MINIO_ROOT_PASSWORD: ${STORAGE_S3_SECRET_KEY:-kixi-minio-secret}
    ports:
      - "${MINIO_PORT:-9000}:9000"
      - "${MINIO_CONSOLE_PORT:-9001}:9001"
    volumes:
      - minio_data:/data
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - kixi-network

  minio-init:
    image: minio/mc:RELEASE.2024-06-13T21-21-32Z
    container_name: kixi-minio-init
    profiles:
      - storage
    depends_on:
      minio:
        condition: service_healthy
    entrypoint: /bin/sh
    command:
      - -c
      - >-
        mc alias set local http://minio:9000
        ${STORAGE_S3_ACCESS_KEY:-kixi-minio}
        ${STORAGE_S3_SECRET_KEY:-kixi-minio-secret}
        && mc mb --ignore-existing local/${STORAGE_S3_BUCKET:-kixi-images}
        && mc anonymous set download local/${STORAGE_S3_BUCKET:-kixi-images}
    networks:
      - kixi-network

# =============================================================================
# Networks
# =============================================================================
networks:
  kixi-network:
    driver: bridge
    name: kixi-network

# =============================================================================
# Volumes
# =============================================================================
volumes:
  # PostgreSQL data persistence
  postgres_data:
    name: kixi-postgres-data

  # PaddleOCR models cache (CPU version)
  ocr_models:
    name: kixi-ocr-models

  # PaddleOCR models cache (GPU version)
  ocr_models_gpu:
    name: kixi-ocr-models-gpu

  # Redis data persistence
  redis_data:
    name: kixi-redis-data

  # MinIO object data for local integration runs
  minio_data:
    name: kixi-minio-data