app.yaml.template

# OntoBricks - Databricks Apps Configuration
# See: https://docs.databricks.com/en/dev-tools/databricks-apps/configuration.html
#
# ╔════════════════════════════════════════════════════════════════╗
# ║  GENERATED FILE — DO NOT EDIT app.yaml DIRECTLY                 ║
# ║                                                                 ║
# ║  This template is rendered into ./app.yaml at deploy time by    ║
# ║  scripts/deploy.sh (which calls scripts/_render-app-yaml.py).   ║
# ║  Edit `scripts/deploy.config.sh` to change the values below,    ║
# ║  then run `make deploy`.                                        ║
# ║                                                                 ║
# ║  app.yaml is .gitignored — only this template is tracked.       ║
# ╚════════════════════════════════════════════════════════════════╝

# Command to run the application (FastAPI with uvicorn).
# uv manages dependencies from pyproject.toml.
#
# `--extra lakebase` installs `psycopg[binary]` and `psycopg-pool`
# (defined in `pyproject.toml`'s optional `[project.optional-dependencies]
# lakebase = [...]`) so the Lakebase Postgres backend works in the
# deployed app even when the `database` resource is not yet bound.
#
# There is deliberately no `--extra neo4j`: the Bolt driver is a *core*
# dependency (see `pyproject.toml`), so the Neo4j engine works when an admin
# selects it in **Settings → Triple store → Global** without an extra. Passing
# `--extra neo4j` makes uv abort with "Extra `neo4j` is not defined in the
# optional-dependencies table", which crashes the app on startup.
#
# Together with the Lakebase extra this powers the runtime backend toggle:
# the admin can switch Volume / Lakebase / Neo4j without redeploying.
#
# Databricks Apps sets DATABRICKS_APP_PORT automatically.
# MCP endpoint is exposed at /mcp (Streamable HTTP transport).
command:
  - "uv"
  - "run"
  # --frozen: use uv.lock verbatim — NEVER re-resolve in the container. The Apps
  # base image defaults uv's index to the internal pypi-proxy, which cold-caches
  # and times out on freshly-published wheels (the v0.6.0 security bumps). The
  # committed lock pins files.pythonhosted.org URLs (public CDN, always warm and
  # container-reachable); --frozen guarantees uv downloads those exact URLs
  # instead of re-locking back to the flaky proxy. Do NOT remove without also
  # pinning the container index away from pypi-proxy.dev.databricks.com.
  - "--frozen"
  - "--no-dev"
  - "--extra"
  - "lakebase"
  - "python"
  - "run.py"

env:
  # SQL Warehouse ID — injected from the configured resource,
  # with a static fallback for MCP / session-less API calls.
  - name: DATABRICKS_SQL_WAREHOUSE_ID
    valueFrom: sql-warehouse
  - name: DATABRICKS_SQL_WAREHOUSE_ID_DEFAULT
    value: "${APP_SQL_WAREHOUSE_FALLBACK}"
  # Default fully-qualified Delta triple store table (catalog.schema.table).
  # Used as fallback when no domain session is active (e.g. MCP API calls).
  - name: DATABRICKS_TRIPLESTORE_TABLE
    value: "${APP_TRIPLESTORE_TABLE}"
  # Domain Registry — injected from the configured Volume resource.
  # The path looks like /Volumes/<catalog>/<schema>/<volume>.
  - name: REGISTRY_VOLUME_PATH
    valueFrom: volume
  # Static fallbacks used for local dev / MCP when no resource is bound.
  - name: REGISTRY_CATALOG
    value: "${APP_REGISTRY_CATALOG}"
  - name: REGISTRY_SCHEMA
    value: "${APP_REGISTRY_SCHEMA}"
  - name: REGISTRY_VOLUME
    value: "${APP_REGISTRY_VOLUME}"
  # App name for permission management — auto-detected at runtime from
  # the Databricks Apps platform (the runtime injects DATABRICKS_APP_NAME
  # as the deployed app's name, e.g. "ontobricks" for prod and
  # "ontobricks-dev" for the dev sandbox). Settings reads it via an
  # alias chain on ONTOBRICKS_APP_NAME -> DATABRICKS_APP_NAME, so the
  # same app.yaml powers every deployment without per-app duplication.
  # Set ONTOBRICKS_APP_NAME explicitly in .env only for local dev.
  #
  # MCP companion app name — must match the deployed MCP Databricks App
  # (``mcp-${APP_NAME}`` from deploy.config.sh). Injected so registry /
  # graph permission grants resolve the right service principal (#137).
  - name: MCP_APP_NAME
    value: "${MCP_APP_NAME}"
  # ── Lakebase (optional) ───────────────────────────────────────
  # When the bundle is deployed to a *-lakebase target the DAB binds
  # a `database` resource to this app. Databricks Apps then
  # auto-injects PGHOST/PGPORT/PGDATABASE/PGUSER/PGAPPNAME/PGSSLMODE
  # into the runtime — no explicit `valueFrom` mapping needed.
  # The OAuth token used as the Postgres password is minted on the fly
  # by `LakebaseAuth` (see src/back/core/databricks/LakebaseAuth.py).
  # Without that resource binding the env vars stay unset and the
  # admin UI keeps the Lakebase backend disabled — the app continues
  # to run normally on the Unity Catalog Volume backend.
  #
  # LAKEBASE_SCHEMA must always be set explicitly (it is NOT injected
  # by the Apps platform).  LAKEBASE_PROJECT, LAKEBASE_DATABASE and LAKEBASE_BRANCH are
  # only resolved at runtime when PGHOST/PGDATABASE are absent (local
  # dev without a bound database resource); in production the platform-
  # injected PG* vars take precedence and these are informational only.
  - name: LAKEBASE_SCHEMA
    value: "${APP_LAKEBASE_SCHEMA}"
  - name: LAKEBASE_PROJECT
    value: "${APP_LAKEBASE_PROJECT}"
  - name: LAKEBASE_DATABASE
    value: "${APP_LAKEBASE_DATABASE}"
  - name: LAKEBASE_BRANCH
    value: "${APP_LAKEBASE_BRANCH}"
  # Lakebase managed-synced: UC catalog for the Lakeflow synced-table
  # registration.  Defaults (when empty) to the registry Volume catalog,
  # which is the personal catalog of the deploying user and may not be
  # accessible by the app service principal.  Set this to a shared/workspace
  # catalog (e.g. "main") when the SP does not have CREATE SCHEMA on the
  # user's personal catalog.
  - name: ONTOBRICKS_SYNC_UC_CATALOG  # optional
    value: "${APP_SYNC_UC_CATALOG}"
  # MLflow — ensure traces are persisted to the workspace tracking server.
  - name: MLFLOW_TRACKING_URI
    value: "${APP_MLFLOW_TRACKING_URI}"
  # ── Knowledge-graph analytics ─────────────────────────────────
  # These mirror the defaults in src/shared/config/settings.py. They are
  # spelled out here so an admin can retune a deployed app without a code
  # change; edit the value, then re-run `make deploy`.
  #
  # In-memory triple cap for community detection (POST /clusters/detect).
  # Graph analytics does not read this — it always runs in the job.
  - name: ONTOBRICKS_ANALYTICS_MAX_TRIPLES
    value: "500000"
  # Top-ranked nodes per metric returned by the job.
  # This is what keeps the persisted payload bounded on a graph of any
  # size; the Analytics page "Top N" selector is capped well below it.
  - name: ONTOBRICKS_ANALYTICS_TOP_N
    value: "100"
  #
  # The serverless job in resources/graph_analytics.job.yml computes every
  # graph KPI, and it is the only thing that does, so leaving this off
  # disables the Analytics page rather than selecting a cheaper calculation.
  #
  # This is only the INITIAL value. Admins flip it at runtime in
  # Settings -> Global ("Compute large-graph metrics on Databricks"), and once
  # they have, their choice overrides this — including an explicit "off"
  # against a "true" here. Changing this value does not un-set an admin's
  # choice.
  #
  # Requires: the bundle deployed (so the job exists), and the domain built
  # at least once. The job reads the mapped-triples snapshot every Build
  # materialises, so it behaves identically on the Delta engine, on Lakebase
  # in either mode, and on Neo4j. A missing prerequisite is reported on the
  # Analytics page by name; nothing falls back to a different calculation.
  # See docs/user-guide.md (Analytics).
  - name: ONTOBRICKS_ANALYTICS_JOB_ENABLED
    value: "false"
  # Deployed name of that job. Leave empty to derive it from the app name
  # as "<app>-graph-analytics", matching the bundle. Only set this if you
  # renamed the job; a bundle deployed in development mode prefixes the
  # name with "[dev <user>] ", which the lookup already allows for.
  - name: ONTOBRICKS_ANALYTICS_JOB_NAME
    value: ""
  # PageRank power iterations. 20 fixes the top-N ordering; raise it only
  # if you need converged absolute scores rather than a ranking.
  - name: ONTOBRICKS_ANALYTICS_JOB_PAGERANK_ITERATIONS
    value: "20"
  # Source nodes sampled for the betweenness/closeness estimates. This is
  # the job's dominant cost — the intermediate search holds one row per
  # (pivot, reachable node), so raising it scales the largest shuffle
  # linearly. "0" skips both metrics and makes the job cheaper; a value at
  # or above the node count makes them exact instead of estimated.
  - name: ONTOBRICKS_ANALYTICS_JOB_PIVOTS
    value: "64"
  # ── Neo4j (optional, legacy Apps secret path) ─────────────────
  # Password may be sourced from a Databricks Apps secret resource (see
  # `resources:` below). The `neo4j-password` resource is unbound by
  # default — DAB does **not** bind it at deploy time (Neo4j is optional;
  # a missing workspace secret would fail terraform apply — GH #136).
  # Preferred path: Settings → Neo4j picks a secret scope/key at runtime
  # (`auth_method: databricks_secret`). Bind this resource in the Apps UI
  # only for legacy `auth_method: basic` + `NEO4J_PASSWORD` configs.
  # See documentation/pr47-neo4j-demo/secret-configuration.md.
  - name: NEO4J_PASSWORD
    valueFrom: neo4j-password

# User authorization scopes — declares which Databricks APIs the app is
# allowed to access on behalf of the logged-in user via the
# x-forwarded-access-token header injected by the Apps platform.
# The app uses the user token exclusively for permission checks
# (SCIM user-group lookup + App ACL read) — all data queries go through
# the app's service principal (M2M OAuth). These two scopes are the
# minimum required; they are also the platform defaults when no scopes
# are declared, but explicit declaration is required for Public Preview.
authorization:
  user:
    scopes:
      - iam.current-user:read
      - iam.access-control:read

# Resources that this app uses.
# Configure these resources in the Databricks Apps UI after deployment.
resources:
  - name: sql-warehouse
    description: "SQL Warehouse for executing queries and metadata operations"
    sql_warehouse:
      permission: CAN_USE
  - name: volume
    description: "Unity Catalog Volume for the OntoBricks domain registry"
    volume:
      permission: CAN_READ_WRITE
  - name: neo4j-password
    description: "Legacy Databricks Apps secret for NEO4J_PASSWORD. Unbound by default — DAB does not bind it (GH #136). Prefer Settings → Neo4j (secret scope/key). Bind in the Apps UI only for legacy auth_method basic. See documentation/pr47-neo4j-demo/secret-configuration.md."
    secret:
      permission: READ