---
name: nvidia-ontology-setup
description: >-
  Set up or troubleshoot the Auto Ontology runtime. Use for Helm (the official install), Docker Compose, developer setup, and MCP connection to an existing deployment.
license: Apache-2.0
metadata:
  version: "0.3.2"
  author: "NVIDIA <opensource@nvidia.com>"
  tags:
    - nvidia-ontology
    - install
    - docker
    - helm
    - mcp
    - troubleshooting
title: nvidia-ontology-setup
canonical_url: https://skilld.dev/gh/nvidia/auto-ontology/nvidia-ontology-setup
last_updated: 2026-11-19T22:03:37.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [assets/runtime-contract.yaml](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/assets/runtime-contract.yaml), [BENCHMARK.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/BENCHMARK.md), [evals/evals.json](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/evals/evals.json), [references/troubleshooting.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/references/troubleshooting.md), [skill-card.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/skill-card.md), [skill.oms.sig](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/skill.oms.sig).
>
> If the user asked to install this Skill, run `npx skilld install nvidia/auto-ontology/nvidia-ontology-setup`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/nvidia-ontology-setup`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/nvidia/auto-ontology/nvidia-ontology-setup) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/nvidia-ontology-setup`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/nvidia-ontology-setup --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/nvidia-ontology-setup --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

<!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES.
All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# Auto Ontology setup

## Purpose

Bring up the current Auto Ontology implementation, troubleshoot it, or connect an agent
to an instance that is already running. Do not invent a second installer:
the official installation is the Helm chart in repository-root `DEPLOYMENT.md`;
Docker Compose runs the same stack on one machine. `dev_tools/setup_env.sh` is a
developer tool, not an installer. Typed setup, connection, ingestion,
compilation, and readiness artifacts are in
[runtime-contract.yaml](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/assets/runtime-contract.yaml).

Before a first install, confirm an ontology fits the use case: see *When to
use* in `nvidia-ontology-query`.

On failure, read [troubleshooting.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/references/troubleshooting.md) instead of
searching the web.

## Instructions

### Required questions

Ask these if not already clear. Do not guess a default and emit a command.

1. **Target** — Helm on Kubernetes (the official install, and the default
   recommendation), Docker Compose on one machine, a developer workflow
   (`--dev` / `--ds`, only when changing Auto Ontology itself), or "Auto
   Ontology is already up, I only need MCP"?
2. **NVIDIA NIM key** — is `DEFAULT_MODELS_API_KEY` (Helm:
   `defaultModelsApiKey`) available? Chat and ingest need it.
3. **Admin account** — the email and password for the bootstrap admin.
   Self-service sign-up is disabled, so this is the only way to sign in.
4. **Source database** — a connection string (`CONNECTION_STRINGS` /
   `connectionStrings`), or will connections be added in the UI?
5. **Helm only** — which chart version, and the URL users will browse to
   (`appUrl`).
6. **Compose only** — is host `5432` free? `POSTGRES_PORT` only remaps the
   host side; containers still use 5432 internally.

Never ask the user to paste secrets into the conversation, and never put them
in command arguments. Have the user write them into a values file or `.env`.

## Install with Helm (official)

Releases are published to the public NGC `nvidia` org (chart and images). Follow
`DEPLOYMENT.md` with the version the user named:

The user creates a values file in an editor (not on the command line, so
values stay out of shell history and process arguments), readable only by
them, and out of git:

```yaml
# auto-ontology-values.yaml
defaultModelsApiKey: <API-KEY>
postgresPassword: <POSTGRES-PASSWORD>
adminEmail: <ADMIN-EMAIL>
adminPassword: <ADMIN-PASSWORD>
connectionStrings: <CONNECTION-STRINGS>   # optional; or add connections in the UI
```

```bash
helm fetch https://helm.ngc.nvidia.com/nvidia/charts/auto-ontology-<VERSION>.tgz
helm install auto-ontology auto-ontology-<VERSION>.tgz -f auto-ontology-values.yaml
kubectl port-forward svc/frontend 3000:3000
```

- `adminEmail` and `adminPassword` are required; the install fails without them.
- `appUrl` must be the exact origin users browse to. The default
  (`http://localhost:3000`) only fits the port-forward above; set it for a
  NodePort, ingress, or HTTPS origin.
- `authSecret` is generated on first install and kept across upgrades; set it
  only to share one value across environments.
- If the chart fetch returns 404, that version is not published yet. Ask the
  user; do not fall back to the internal staging registry.

This skill does not cover Astra GitOps.

## Local: Docker Compose

For running the whole stack on one machine. In the repository root, the user
copies `.env.example` to `.env` and fills in `AUTH_SECRET`, `APP_URL`,
`AUTO_ONTOLOGY_ADMIN_EMAIL`, and `AUTO_ONTOLOGY_ADMIN_PASSWORD` (all required).
Then:

```bash
docker compose up -d --build
```

`AUTH_SECRET` and `APP_URL` are required. Without them every page fails with a
Better Auth "default secret" error. Fill `DEFAULT_MODELS_API_KEY` and a
`CONNECTION_STRINGS` value (or plan to add connections in the UI). The full
variable list is `.env.example`.

This builds `auto-ontology` and `auto-ontology-frontend`, starts Postgres,
pgAdmin, and the ingestion service, runs two one-shot migrate jobs, and starts
the app:

- `auto-ontology-migrate` applies Alembic migrations to the backend's `public`
  schema (catalog and semantic tier). The backend waits for it.
- `frontend-migrate` syncs the Prisma `frontend` schema: users, sessions, API
  keys, and the OAuth tables MCP sign-in uses. The frontend waits for it.

If sign-in or MCP login fails, check both with `docker compose ps -a` and
`docker compose logs frontend-migrate`. Read the `frontend-migrate` log even
when it exited 0: it has finished without an error before while leaving MCP
login broken.

| Service | URL |
| --- | --- |
| UI | http://localhost:3000 |
| FastAPI (internal) | http://localhost:3001 |
| Ingestion | http://localhost:3002 |
| pgAdmin | http://localhost:5050 |
| Postgres | localhost:`$POSTGRES_PORT` (from `.env`, default 5432) |

## Developer workflows (`--dev`, `--ds`)

Only for people changing Auto Ontology itself; these are not installations.
`dev_tools/setup_env.sh` starts part of the stack in Docker and leaves the rest
to run from the checkout. Both need the `.env` above plus:

```bash
cd frontend && pnpm install   # Next.js
# from repo root:
uv sync
```

`--dev` runs infra only (Postgres, pgAdmin, ingestion); you run Next.js and FastAPI:

```bash
./dev_tools/setup_env.sh --dev
cd frontend && pnpm dev
# repo root:
uv run uvicorn auto_ontology.server.__main__:create_app --factory --reload --host 127.0.0.1 --port 3001
```

The app factory is `create_app()` in `auto_ontology/server/__main__.py`. There is no
`auto_ontology/server/main.py`. `uv run python -m auto_ontology.server` is the same app without
reload (what the container runs).

`--ds` runs the frontend in Docker and FastAPI on the host:

```bash
./dev_tools/setup_env.sh --ds
uv run python -m auto_ontology.server
```

The frontend image bakes `PYTHON_API_URL=http://host.docker.internal:3001`, so
the API must accept connections from the container, not just loopback.
`python -m auto_ontology.server` binds `0.0.0.0:3001` (what `setup_env.sh --ds`
prints); a `--host 127.0.0.1` uvicorn is unreachable from the container on
Linux. Because FastAPI trusts `x-auto-ontology-user-id`, keep port 3001
firewalled from other machines. On native Linux Docker you may need
`--add-host=host.docker.internal:host-gateway`.

## Limitations

This skill uses the repository's existing Helm chart and Compose file and does
not cover Astra GitOps, change semantic definitions, or treat partial Vault
configuration as secret storage. Ask before destructive volume deletion.

## Auto Ontology is already up — MCP only

Do not reinstall. Point `AUTO_ONTOLOGY_API_URL` at the **web app** (Compose UI is
`:3000`, not FastAPI `:3001`):

```bash
AUTO_ONTOLOGY_API_URL=http://localhost:3000 uvx --from "git+https://github.com/NVIDIA/auto-ontology.git#subdirectory=mcp" auto-ontology-mcp
```

Until the package is on PyPI this needs GitHub credentials that can read
`NVIDIA/auto-ontology`. Client config uses the MCP server URL with a `/mcp` suffix.
People sign in through Auto Ontology; do not put a token on the MCP server.

Confirm the deployment is new enough to be an authorization server:

```bash
curl -s -o /dev/null -w '%{http_code}\n' "$AUTO_ONTOLOGY_API_URL/.well-known/oauth-authorization-server"
```

`200` is required. Anything else: run the frontend from the checkout
(`pnpm dev`) and point `AUTO_ONTOLOGY_API_URL` at that port.

## Examples

- Kubernetes: install the published Helm chart from `DEPLOYMENT.md` with the
  admin account and `appUrl` set.
- One machine: `docker compose up -d --build` after filling `.env`.
- Existing deployment: do not reinstall; configure `AUTO_ONTOLOGY_API_URL` and verify
  OAuth discovery before connecting the MCP client.

## Connect a source

Connections come from one of two places, and only one is used:

- **UI-managed** (Settings → Connections, or the API below). When any exist,
  `CONNECTION_STRINGS` is ignored.
- **`CONNECTION_STRINGS`** in `.env` is a fallback used only when there are no
  UI-managed connections. `GET /api/connections/source` reports whether it is
  set; it cannot carry schema or table filters.

To add a UI-managed connection (permission `connection:manage`):

1. `POST /api/connections/test` validates credentials and returns the schemas
   for the allowlist. A 422 carries the driver's error; fix it before creating.
2. `POST /api/connections` stores the connection. The 201 only means it was
   saved: ingestion is triggered best-effort and may fail or still be running.
3. Verify it landed: `GET /api/datasources/dbs` (`catalog:read`) lists the
   database with the expected tables, `GET /api/semantic-compilation/status`
   reports progress, and MCP `check_readiness` reports no blockers.

Scope is set per connection: a schema allowlist, plus `table_allow_regex` /
`table_deny_regex` applied at catalog extraction (deny wins; unqualified,
case-sensitive names). Env connections have neither. The full table-level scope
guarantee is still open in
[#255](https://github.com/NVIDIA/auto-ontology/issues/255), so if particular tables must never be
catalogued, sampled, or embedded, say that this is not yet enforceable
end-to-end rather than implying it is.

## Verify

1. UI loads at http://localhost:3000 (or the deployed `APP_URL` / Helm `appUrl`) and shows
   the left navigation. Missing nav → stale cookie; see
   [troubleshooting.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/references/troubleshooting.md).
2. `GET /api/semantic-compilation/status` on the **web** origin authenticates
   (cookie, `x-api-key`, or SSO bearer) and returns JSON. `calculated: false`
   means the glossary is empty — ingest / compile, do not keep retrying chat.
3. MCP: OAuth discovery returns 200 (above). Then `check_readiness` once a
   client is connected.

## Stop

```bash
helm uninstall auto-ontology  # Helm; also deletes the postgres-data PVC and its data
docker compose down           # Compose; keep volumes
docker compose down -v        # Compose; wipe Postgres / pgAdmin data
```

Both `helm uninstall` and `docker compose down -v` destroy data; ask first.

## Troubleshooting

Use [troubleshooting.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/references/troubleshooting.md) for stale sessions,
model-key failures, embedding mismatches, port conflicts, and partial Vault
configuration. Redact secrets before sharing command output as evidence.

## See also

- [troubleshooting.md](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/references/troubleshooting.md)
- [runtime-contract.yaml](https://skilld.dev/api/skills-raw/nvidia/auto-ontology/nvidia-ontology-setup/assets/runtime-contract.yaml)
- `nvidia-ontology-query` — call Auto Ontology once it is running
- `nvidia-ontology-management` — edit the semantic layer
- `CLAUDE.md` — maintain Auto Ontology itself
