Deploy OntoBricks to your Databricks workspace

A complete, from-scratch guide to installing OntoBricks as a native Databricks App — from an empty workspace to a running app your whole team can open. Everything deploys from a single Databricks Asset Bundle.

~20 min Databricks Apps One-command deploy

Prerequisites

OntoBricks deploys as a Databricks App using a Databricks Asset Bundle (DAB) — one command deploys both the web app and its MCP companion. Before you start, make sure the workspace and your machine have the following.

In the workspace

  • Databricks Apps enabled, and permission to create/manage apps
  • A running SQL Warehouse (note its ID)
  • A Unity Catalog catalog + schema + Volume for the registry
  • A Databricks Lakebase (Autoscaling) project — created in Step 3

On your machine

  • Databricks CLI ≥ 0.250.0 (databricks -v)
  • git, to clone the deployment bundle
  • psql (libpq client) on your PATH for the Lakebase permission scripts

The app runs as a service principal. It needs Unity Catalog grants on the registry catalog/schema/volume and on every source table you'll map. The exact grants are in the Deployment Guide → UC permissions; the deploy script and the in-app Initialize flow apply most of them for you.

1 Install & authenticate the Databricks CLI

bash 
# Install the CLI (>= 0.250.0)
brew install databricks            # or: curl -fsSL https://databricks.com/install.sh | sh
databricks -v

# Log in to your workspace (opens a browser)
databricks auth login --host https://<workspace>.cloud.databricks.com

# Verify you're connected
databricks current-user me

2 Get the code

Clone the repository — the Asset Bundle and deploy scripts live inside it.

bash 
git clone https://github.com/databrickslabs/ontobricks
cd ontobricks

3 Create the Lakebase project

OntoBricks stores its domain registry and graph triple store in Lakebase Postgres. Create the project once per workspace with the bundled script — it provisions the instance, waits for it to become available, and creates the Postgres database:

bash 
# Creates the Lakebase instance + database (once per workspace)
./scripts/bootstrap/setup-lakebase.sh --name ontobricks-demo --capacity CU_2

# It prints the db-… resource id at the end — you usually don't
# need to copy it; deploy.sh resolves it automatically in Step 4/5.

Don't use the workspace "New project" button. The UI (Compute → Postgres → New project) calls a different API that is incompatible with the Synced Tables used by the Knowledge Graph build. Always create the Lakebase project with scripts/bootstrap/setup-lakebase.sh.

Note the project name, branch (default production), and database name (default ontobricks_demo) — you'll enter them in the next step.

4 Configure the deploy

All workspace-specific values live in one file: scripts/deploy.config.sh. The bundle's app.yaml is generated from it at deploy time — edit the config, not app.yaml. Set the defaults to match your workspace:

scripts/deploy.config.sh 
# CLI profile (empty = default from `databricks auth profiles`)
DEFAULT_DATABRICKS_PROFILE=""
# One knob for the instance → app name + deploy target
DEFAULT_INSTANCE_ID="demo"                 # → app "ontobricks-demo"

# SQL Warehouses → your warehouse → Connection details
DEFAULT_WAREHOUSE_ID="abc123def456"

# Unity Catalog registry namespace (the volume must already exist)
DEFAULT_REGISTRY_CATALOG="main"
DEFAULT_REGISTRY_SCHEMA="default"
DEFAULT_REGISTRY_VOLUME="OntoBricksRegistry"

# Lakebase — the project you created in Step 3
DEFAULT_LAKEBASE_PROJECT="ontobricks-demo"
DEFAULT_LAKEBASE_BRANCH="production"
DEFAULT_LAKEBASE_DATABASE="ontobricks_demo"   # Postgres datname (NOT the db-… id)
DEFAULT_LAKEBASE_SCHEMA="ontobricks_registry" # Postgres schema for the registry

You can override any value for a single run without editing the file, e.g. WAREHOUSE_ID=abc123 make deploy. See the full variable reference in the Deployment Guide → deploy.config.sh.

5 Deploy the apps

One command validates the bundle, deploys both apps (the web UI and the MCP server), starts them, and applies the registry Lakebase grants:

bash 
# Recommended — validate + deploy + start both apps
scripts/deploy.sh

# …or drive the bundle directly
databricks bundle validate -t dev-lakebase
databricks bundle deploy   -t dev-lakebase

Every step is idempotent, so it's safe to re-run scripts/deploy.sh after changing config. On the first run the MCP app's URL doesn't exist yet — just re-run once the web app is up so the MCP server picks it up.

6 Bind resources (first deploy only)

Confirm the app's resources are wired to your workspace objects. Do this once — bindings persist across redeploys.

  1. Go to Compute → Apps and open your app (e.g. ontobricks-demo).
  2. Click Resources and confirm/bind:
    • sql-warehouse → your running SQL Warehouse
    • volume → the Unity Catalog Volume for the registry
    • postgres → the Lakebase database from Step 3
  3. Repeat for the mcp-ontobricks app (same warehouse and volume).
  4. Verify both apps show status Running.

Once sql-warehouse and volume are bound, the matching controls in the app's Settings page are locked — change them by editing the resource bindings here and restarting the app.

7 Initialize the registry (first deploy only)

  1. Open the app URL and go to Settings → Registry.
  2. Click Initialize. This creates the registry schema in Lakebase and — on the Lakebase backend — self-applies the Postgres grants the app and MCP service principals need (shown under Permission Grants).
  3. If any Unity Catalog grants are still missing, a workspace admin can re-run scripts/bootstrap/lakebase-perms.sh -c <catalog>. Use Repair permissions on the Lakebase Connection panel to re-apply schema grants later (e.g. after a rebind).

One-click graph DB. When you later build a Knowledge Graph, admins can provision the graph store without any shell scripts: Settings → Lakebase → Connection has a "Create graph DB from scratch" button that creates the instance, database and schema and applies all grants as a live async job.

8 Grant access & assign roles

When running as a Databricks App, OntoBricks enforces role-based access. On first deploy, only users with CAN_MANAGE on the app can get in — everyone else is blocked until you assign them a role.

  1. Grant workspace users access to the app in Databricks → Apps → <your app> → Permissions (CAN_USE to open it, CAN_MANAGE for admins).
  2. In the app, open Settings → Admin → Teams to assign per-domain roles:
    • Admin — users with CAN_MANAGE on the app; manage roles and settings.
    • Editor — full read/write on all features.
    • Viewer — read-only access.

9 Verify & open

bash 
# Check both apps (names match databricks.yml)
databricks apps get ontobricks-demo
databricks apps get mcp-ontobricks

# …or a bundle summary
databricks bundle summary -t dev-lakebase

Open the app URL from the Apps page — OntoBricks is deployed. Head to the Getting Started guide to build your first knowledge graph.

MCP companion app

The Model Context Protocol server ships in the same bundle and deploys alongside the web app as mcp-ontobricks. Because its name starts with mcp-, it appears automatically in the Databricks Playground once running — no extra deployment needed. To (re)start it on its own:

bash 
databricks bundle run mcp_ontobricks_app -t dev-lakebase

Using the graph from an agent is covered in Getting Started → Use it via MCP.

Troubleshooting

Everyone lands on "access denied"

On first deploy only CAN_MANAGE users have access. Grant app access in Apps → Permissions, then assign roles in Settings → Admin → Teams (Step 8).

App won't reach "Running"

Check that the sql-warehouse, volume, and postgres resources are bound (Step 6), and that the SQL Warehouse is started.

Registry / graph errors after deploy

Make sure you ran Settings → Registry → Initialize, and that the app service principal has the Unity Catalog grants — re-run scripts/bootstrap/lakebase-perms.sh -c <catalog> as an admin if needed.

Settings fields are locked

That's expected when a resource is bound. Change the value in Compute → Apps → Resources and restart the app.

For the full checklist — UC grants, Lakebase schema bootstrap, upgrade notes — see the Deployment Guide.

Next steps

Guide Build your first graph → From a new domain to a queryable knowledge graph and MCP. Reference Deployment Guide → Full DAB reference, UC grants, MCP wiring, upgrades — and local dev. Support Report an issue ↗ Hit a snag deploying? File it on GitHub.