Nvidia Ontology Setup

<!--
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.

On failure, read 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:

# 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

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:

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.

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:

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

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

./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:

./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.