service:
  name: kb-query
  owner_node: piha
  role: kb-search-api            # module 5 phase 4: first user-facing HTTP entry point to the KB (API + minimal search UI, plan §7)
  exposure: private               # LAN/Tailscale only, npm@PIHA vhost (kb.kapala.org) is a later step
  dependencies:
    - kb-postgres
    - forgejo                     # OIDC identity provider, wired in a later step (plan §8); not yet enforced
  # ollama@SOLARIA is an external, optional runtime dependency (embed calls), not a hard
  # dependency here -- SOLARIA may be offline; /search then fails per-request with 503,
  # /healthz still answers (same tolerance pattern as llm-gateway).
  ports:
    - container: 8080
      host: 8230                  # LAN_BIND_IP only, never 0.0.0.0
      protocol: tcp
  healthcheck:
    type: http
    endpoint: http://192.168.31.5:8230/healthz   # LAN bind — localhost does not answer
    interval: 30s
    timeout: 10s
    retries: 5
  restart_policy: unless-stopped
  persistence:
    paths: []                     # stateless — kb-postgres holds all state
  runtime:
    config_files:
      - .env                      # KB_DSN, LAN_BIND_IP (gitignored, from env.example)
    env_vars:
      - LAN_BIND_IP                # required — compose port-bind interpolation
      - KB_DSN                     # required — asyncpg DSN for kb-postgres@PIHA
      - OLLAMA_URL                 # optional — defaults to http://solaria:11434
      - EMBED_MODEL                 # optional — defaults to bge-m3; startup invariant vs document_chunk/document_summary
      - SUMMARY_MODEL               # optional — defaults to claude-haiku-4-5; cascade_query's stage-1 model