docker-compose.yml

# =============================================================================
# OpenMRS AI Query Agent — local development and evaluation stack
#
# Profiles keep the default start-up light. Without a profile you get the
# services the agent itself needs:
#
#   docker compose up -d                 qdrant + redis + api
#   docker compose --profile ai up -d    ... plus a local Ollama runtime
#   docker compose --profile demo up -d  ... plus a real OpenMRS to query
#   docker compose --profile obs up -d   ... plus Prometheus, Grafana, Loki
#
# The `demo` profile exists because this system must never be developed
# against a guessed schema. It starts a genuine OpenMRS instance whose
# database the agent introspects, so Phase 2 reads a real schema and a real
# concept dictionary rather than an assumed one.
# =============================================================================

name: openmrs-query-agent

x-restart: &restart
  restart: unless-stopped

x-logging: &logging
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

services:
  # ---------------------------------------------------------------------------
  # Vector database — documentation, schema cards, concepts, SQL exemplars
  # ---------------------------------------------------------------------------
  qdrant:
    image: qdrant/qdrant:v1.12.5
    container_name: oqa-qdrant
    <<: [*restart, *logging]
    ports:
      - "${QDRANT_HTTP_PORT:-6333}:6333"
      - "${QDRANT_GRPC_PORT:-6334}:6334"
    volumes:
      - qdrant-data:/qdrant/storage
    environment:
      QDRANT__SERVICE__API_KEY: ${OQA_VECTOR__API_KEY:-}
      QDRANT__LOG_LEVEL: INFO
    healthcheck:
      # The image is distroless, so no curl: use Qdrant's own TCP readiness
      # via a bash redirect, which needs no extra binary.
      test: ["CMD-SHELL", "timeout 2 bash -c '</dev/tcp/localhost/6333' || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  # ---------------------------------------------------------------------------
  # Cache — embeddings, schema snapshots, answered questions
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7.4-alpine
    container_name: oqa-redis
    <<: [*restart, *logging]
    ports:
      - "${REDIS_PORT:-6379}:6379"
    volumes:
      - redis-data:/data
    # appendonly keeps the cache warm across restarts; maxmemory-policy evicts
    # least-recently-used entries rather than erroring when the cap is reached.
    command: >
      redis-server
      --appendonly yes
      --maxmemory ${REDIS_MAXMEMORY:-512mb}
      --maxmemory-policy allkeys-lru
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5

  # ---------------------------------------------------------------------------
  # The agent
  # ---------------------------------------------------------------------------
  api:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        EXTRAS: "ai,rag,mcp,auth,reporting"
    image: openmrs-query-agent:${OQA_IMAGE_TAG:-dev}
    container_name: oqa-api
    <<: [*restart, *logging]
    depends_on:
      qdrant:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "${OQA_API_PORT:-8000}:8000"
    env_file:
      - .env
    environment:
      # Inside the compose network, services resolve by name. These override
      # the localhost defaults in .env without requiring a separate file.
      OQA_VECTOR__URL: http://qdrant:6333
      OQA_CACHE__URL: redis://redis:6379/0
      OQA_LOG_FORMAT: json
      # `localhost` inside a container is the container, not the host, so an
      # Ollama running on the workstation is reached through the gateway.
      # With `--profile ai`, set OQA_DOCKER_LLM_URL=http://ollama:11434 to use
      # the containerised runtime instead.
      OQA_LLM__BASE_URL: ${OQA_DOCKER_LLM_URL:-http://host.docker.internal:11434}
      OQA_EMBEDDING__BASE_URL: ${OQA_DOCKER_LLM_URL:-http://host.docker.internal:11434}
      # Same reasoning for a MySQL running on the workstation. Point this at a
      # real hostname when the clinical database is on another machine.
      OQA_DB__HOST: ${OQA_DOCKER_DB_HOST:-host.docker.internal}
    extra_hosts:
      # Docker Desktop resolves this automatically; the mapping is what makes
      # it work on plain Linux Docker too.
      - "host.docker.internal:host-gateway"
    volumes:
      - agent-data:/app/.data
      - ./exports:/app/exports
    security_opt:
      - no-new-privileges:true
    healthcheck:
      test: ["CMD", "curl", "--fail", "--silent", "http://localhost:8000/health/live"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 20s

  # ---------------------------------------------------------------------------
  # Local inference (profile: ai)
  # ---------------------------------------------------------------------------
  # Keeps every token on-premise. A clinical question is itself protected
  # health information, so the default deployment does not send one to a
  # third-party API.
  ollama:
    image: ollama/ollama:latest
    container_name: oqa-ollama
    profiles: ["ai"]
    <<: [*restart, *logging]
    ports:
      - "${OLLAMA_PORT:-11434}:11434"
    volumes:
      - ollama-models:/root/.ollama
    environment:
      OLLAMA_KEEP_ALIVE: "30m"
      OLLAMA_NUM_PARALLEL: "2"
    # Uncomment for NVIDIA acceleration. On CPU, expect tens of seconds per
    # SQL generation with a 14B model; size the model to the hardware.
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]
    healthcheck:
      test: ["CMD-SHELL", "ollama list >/dev/null 2>&1 || exit 1"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 30s

  # ---------------------------------------------------------------------------
  # Reference OpenMRS to develop against (profile: demo)
  # ---------------------------------------------------------------------------
  # First boot runs Liquibase over an empty database and takes several minutes.
  # Watch progress with: docker compose logs -f openmrs
  openmrs-db:
    image: mariadb:10.11
    container_name: oqa-openmrs-db
    profiles: ["demo"]
    <<: [*restart, *logging]
    command: >
      mysqld
      --character-set-server=utf8mb4
      --collation-server=utf8mb4_unicode_ci
      --max_allowed_packet=64M
    ports:
      - "${OPENMRS_DB_PORT:-3306}:3306"
    volumes:
      - openmrs-db-data:/var/lib/mysql
      # Creates the read-only account the agent uses. Runs once, on the first
      # boot of an empty data volume.
      - ./scripts/docker/init-readonly-user.sh:/docker-entrypoint-initdb.d/01-init-readonly-user.sh:ro
    environment:
      MARIADB_DATABASE: ${OPENMRS_DB_NAME:-openmrs}
      MARIADB_USER: ${OPENMRS_DB_USER:-openmrs}
      MARIADB_PASSWORD: ${OPENMRS_DB_PASSWORD:-openmrs}
      MARIADB_ROOT_PASSWORD: ${OPENMRS_DB_ROOT_PASSWORD:-openmrs}
      # Consumed by the init script above.
      OQA_READONLY_PASSWORD: ${OQA_DB__PASSWORD:-oqa_readonly_password}
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      interval: 10s
      timeout: 5s
      retries: 20
      start_period: 30s

  openmrs:
    image: openmrs/openmrs-reference-application-3-backend:${OPENMRS_TAG:-demo}
    container_name: oqa-openmrs
    profiles: ["demo"]
    <<: [*restart, *logging]
    depends_on:
      openmrs-db:
        condition: service_healthy
    ports:
      - "${OPENMRS_PORT:-8090}:8080"
    volumes:
      - openmrs-data:/openmrs/data
    environment:
      OMRS_CONFIG_MODULE_WEB_ADMIN: "true"
      OMRS_CONFIG_AUTO_UPDATE_DATABASE: "true"
      OMRS_CONFIG_CREATE_TABLES: "true"
      OMRS_CONFIG_CONNECTION_SERVER: openmrs-db
      OMRS_CONFIG_CONNECTION_DATABASE: ${OPENMRS_DB_NAME:-openmrs}
      OMRS_CONFIG_CONNECTION_USERNAME: ${OPENMRS_DB_USER:-openmrs}
      OMRS_CONFIG_CONNECTION_PASSWORD: ${OPENMRS_DB_PASSWORD:-openmrs}
    healthcheck:
      test: ["CMD-SHELL", "curl --fail --silent http://localhost:8080/openmrs/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 30
      start_period: 180s

  # ---------------------------------------------------------------------------
  # Observability (profile: obs)
  # ---------------------------------------------------------------------------
  prometheus:
    image: prom/prometheus:v3.1.0
    container_name: oqa-prometheus
    profiles: ["obs"]
    <<: [*restart, *logging]
    ports:
      - "${PROMETHEUS_PORT:-9090}:9090"
    volumes:
      - ./deploy/docker/prometheus.yml:/etc/prometheus/prometheus.yml:ro
      - prometheus-data:/prometheus
    command:
      - --config.file=/etc/prometheus/prometheus.yml
      - --storage.tsdb.retention.time=15d
      - --web.enable-lifecycle

  loki:
    image: grafana/loki:3.3.2
    container_name: oqa-loki
    profiles: ["obs"]
    <<: [*restart, *logging]
    ports:
      - "${LOKI_PORT:-3100}:3100"
    volumes:
      - loki-data:/loki
    command: -config.file=/etc/loki/local-config.yaml

  grafana:
    image: grafana/grafana:11.4.0
    container_name: oqa-grafana
    profiles: ["obs"]
    <<: [*restart, *logging]
    depends_on: [prometheus, loki]
    ports:
      - "${GRAFANA_PORT:-3001}:3000"
    volumes:
      - grafana-data:/var/lib/grafana
      - ./deploy/docker/grafana-datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml:ro
    environment:
      GF_SECURITY_ADMIN_PASSWORD: ${GRAFANA_PASSWORD:-admin}
      GF_USERS_ALLOW_SIGN_UP: "false"
      GF_AUTH_ANONYMOUS_ENABLED: "false"

volumes:
  qdrant-data:
  redis-data:
  agent-data:
  ollama-models:
  openmrs-db-data:
  openmrs-data:
  prometheus-data:
  loki-data:
  grafana-data: