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

Configuration automatique de Auto Ontology

Objectif

Déployer l'implémentation actuelle d'Auto Ontology, la dépanner ou connecter un agent à une instance déjà en cours d'exécution. Ne pas inventer un deuxième installeur : l'installation officielle est le chart Helm dans DEPLOYMENT.md à la racine du dépôt ; Docker Compose exécute la même pile sur une seule machine. dev_tools/setup_env.sh est un outil de développeur, pas un installeur. Les artefacts de configuration, connexion, ingestion, compilation et disponibilité typés se trouvent dans runtime-contract.yaml.

En cas d'erreur, consultez troubleshooting.md au lieu de faire une recherche sur le web.

Instructions

Questions obligatoires

Posez ces questions si ce n'est pas déjà clair. Ne pas deviner une valeur par défaut et émettre une commande.

1. Cible — Helm sur Kubernetes (l'installation officielle et la recommandation par défaut), Docker Compose sur une machine, un workflow de développeur (--dev / --ds, uniquement lors de modifications d'Auto Ontology lui-même), ou « Auto Ontology est déjà déployé, j'ai seulement besoin de MCP » ?
2. Clé NVIDIA NIM — DEFAULT_MODELS_API_KEY (Helm : defaultModelsApiKey) est-elle disponible ? Chat et ingestion en ont besoin.
3. Compte administrateur — l'email et le mot de passe de l'administrateur de bootstrap. L'inscription en libre-service est désactivée, c'est donc le seul moyen de se connecter.
4. Base de données source — une chaîne de connexion (CONNECTION_STRINGS / connectionStrings), ou les connexions seront-elles ajoutées dans l'UI ?
5. Helm uniquement — quelle version du chart, et l'URL que les utilisateurs consulteront (appUrl).
6. Compose uniquement — l'hôte 5432 est-il libre ? POSTGRES_PORT ne remet en place que le côté hôte ; les conteneurs utilisent toujours 5432 en interne.

Ne jamais demander à l'utilisateur de coller des secrets dans la conversation, et ne jamais les mettre dans les arguments de commande. Faire en sorte que l'utilisateur les écrive dans un fichier de valeurs ou .env.

Installation avec Helm (officielle)

Les versions sont publiées sur l'organisation publique NGC nvidia (chart et images). Suivez DEPLOYMENT.md avec la version nommée par l'utilisateur :

L'utilisateur crée un fichier de valeurs dans un éditeur (pas sur la ligne de commande, pour que les valeurs restent en dehors de l'historique du shell et des arguments des processus), lisible uniquement par lui, et en dehors de git :

# auto-ontology-values.yaml
defaultModelsApiKey: <API-KEY>
postgresPassword: <POSTGRES-PASSWORD>
adminEmail: <ADMIN-EMAIL>
adminPassword: <ADMIN-PASSWORD>
connectionStrings: <CONNECTION-STRINGS>   # optional; ou ajouter des connexions dans l'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 et adminPassword sont obligatoires ; l'installation échoue sans eux.
• appUrl doit être l'origine exacte que les utilisateurs consultent. La valeur par défaut (http://localhost:3000) ne convient que pour le port-forward ci-dessus ; la définir pour une NodePort, une ingress ou une origine HTTPS.
• authSecret est généré à la première installation et conservé lors des mises à jour ; la définir uniquement pour partager une valeur entre les environnements.
• Si la récupération du chart retourne 404, cette version n'est pas encore publiée. Demandez à l'utilisateur ; ne pas revenir au registre de staging interne.

Cette compétence ne couvre pas Astra GitOps.

Local : Docker Compose

Pour exécuter la pile entière sur une machine. À la racine du dépôt, l'utilisateur copie .env.example en .env et remplit AUTH_SECRET, APP_URL, AUTO_ONTOLOGY_ADMIN_EMAIL, et AUTO_ONTOLOGY_ADMIN_PASSWORD (tous obligatoires). Puis :

docker compose up -d --build

AUTH_SECRET et APP_URL sont obligatoires. Sans eux, chaque page échoue avec une erreur Better Auth « default secret ». Remplir DEFAULT_MODELS_API_KEY et une valeur CONNECTION_STRINGS (ou prévoir d'ajouter des connexions dans l'UI). La liste complète des variables se trouve dans .env.example.

Cela construit auto-ontology et auto-ontology-frontend, démarre Postgres, pgAdmin et le service d'ingestion, exécute deux tâches de migration ponctuelles, et lance l'application :

• auto-ontology-migrate applique les migrations Alembic au schéma public du backend (catalogue et couche sémantique). Le backend attend.
• frontend-migrate synchronise le schéma Prisma frontend : utilisateurs, sessions, clés API, et les tables OAuth que la connexion MCP utilise. Le frontend attend.

Si la connexion ou la connexion MCP échoue, vérifiez les deux avec docker compose ps -a et docker compose logs frontend-migrate. Lisez le log de frontend-migrate même s'il a quitté avec le code 0 : il s'est terminé sans erreur auparavant tout en laissant la connexion MCP cassée.

Workflows de développeur (--dev, --ds)

Uniquement pour les personnes modifiant Auto Ontology lui-même ; ce ne sont pas des installations. dev_tools/setup_env.sh démarre une partie de la pile en Docker et laisse le reste s'exécuter depuis le checkout. Les deux ont besoin du .env ci-dessus plus :

cd frontend && pnpm install   # Next.js
# à partir de la racine du dépôt :
uv sync

--dev exécute l'infra uniquement (Postgres, pgAdmin, ingestion) ; vous lancez Next.js et FastAPI :

./dev_tools/setup_env.sh --dev
cd frontend && pnpm dev
# racine du dépôt :
uv run uvicorn auto_ontology.server.__main__:create_app --factory --reload --host 127.0.0.1 --port 3001

La fabrique d'application est create_app() dans auto_ontology/server/__main__.py. Il n'y a pas de auto_ontology/server/main.py. uv run python -m auto_ontology.server est la même application sans reload (ce que le conteneur exécute).

--ds exécute le frontend en Docker et FastAPI sur l'hôte :

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

L'image frontend bake PYTHON_API_URL=http://host.docker.internal:3001, donc l'API doit accepter les connexions depuis le conteneur, pas seulement la loopback. python -m auto_ontology.server se lie à 0.0.0.0:3001 (ce que setup_env.sh --ds affiche) ; un uvicorn --host 127.0.0.1 est inaccessible depuis le conteneur sur Linux. Comme FastAPI fait confiance à x-auto-ontology-user-id, gardez le port 3001 firewall des autres machines. Sur Docker Linux natif, vous pouvez avoir besoin de --add-host=host.docker.internal:host-gateway.

Limitations

Cette compétence utilise le chart Helm et le fichier Compose existants du dépôt et ne couvre pas Astra GitOps, la modification des définitions sémantiques, ou le traitement d'une configuration partielle de Vault comme stockage secret. Demander avant la suppression destructrice de volumes.

Auto Ontology est déjà déployé — MCP uniquement

Ne pas réinstaller. Pointer AUTO_ONTOLOGY_API_URL vers l'application web (l'UI Compose est :3000, pas FastAPI :3001) :

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

Jusqu'à ce que le paquet soit sur PyPI, cela nécessite des identifiants GitHub qui peuvent lire NVIDIA/auto-ontology. La configuration du client utilise l'URL du serveur MCP avec un suffixe /mcp. Les utilisateurs se connectent via Auto Ontology ; ne pas mettre de token sur le serveur MCP.

Confirmer que le déploiement est assez récent pour être un serveur d'autorisation :

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

200 est requis. N'importe quoi d'autre : exécuter le frontend depuis le checkout (pnpm dev) et pointer AUTO_ONTOLOGY_API_URL sur ce port.

Exemples

• Kubernetes : installer le chart Helm publié depuis DEPLOYMENT.md avec le compte administrateur et appUrl définis.
• Une machine : docker compose up -d --build après avoir rempli .env.
• Déploiement existant : ne pas réinstaller ; configurer AUTO_ONTOLOGY_API_URL et vérifier la découverte OAuth avant de connecter le client MCP.

Connecter une source

Les connexions proviennent de l'une de deux places, et une seule est utilisée :

• Gérées par l'UI (Paramètres → Connexions, ou l'API ci-dessous). Quand il en existe, CONNECTION_STRINGS est ignoré.
• CONNECTION_STRINGS dans .env est une valeur par défaut utilisée uniquement quand il n'y a pas de connexions gérées par l'UI. GET /api/connections/source rapporte si elle est définie ; elle ne peut pas porter de filtres de schéma ou table.

Pour ajouter une connexion gérée par l'UI (permission connection:manage) :

1. POST /api/connections/test valide les identifiants et retourne les schémas pour la liste blanche. Un 422 porte l'erreur du pilote ; la corriger avant de créer.
2. POST /api/connections sauvegarde la connexion. Le 201 signifie seulement qu'elle a été enregistrée : l'ingestion est déclenchée au mieux et peut échouer ou être toujours en cours.
3. Vérifier qu'elle est arrivée : GET /api/datasources/dbs (catalog:read) liste la base de données avec les tables attendues, GET /api/semantic-compilation/status rapporte la progression, et MCP check_readiness ne rapporte aucun bloqueur.

La portée est définie par connexion : une liste blanche de schéma, plus table_allow_regex / table_deny_regex appliqué à l'extraction du catalogue (deny gagne ; noms non qualifiés, sensibles à la casse). Les connexions env n'en ont aucune. La garantie complète de portée au niveau table est toujours ouverte dans #255, donc si des tables particulières ne doivent jamais être cataloguées, échantillonnées ou intégrées, dire que ce n'est pas encore applicable de bout en bout plutôt que d'impliquer que c'est le cas.

Vérifier

1. L'UI se charge à http://localhost:3000 (ou le APP_URL déployé / Helm appUrl) et affiche la navigation gauche. Navigation manquante → cookie périmé ; voir troubleshooting.md.
2. GET /api/semantic-compilation/status sur l'origine web s'authentifie (cookie, x-api-key, ou bearer SSO) et retourne du JSON. calculated: false signifie que le glossaire est vide — ingérer / compiler, ne pas continuer à relancer le chat.
3. MCP : la découverte OAuth retourne 200 (ci-dessus). Puis check_readiness une fois qu'un client est connecté.

Arrêter

helm uninstall auto-ontology  # Helm ; supprime aussi le PVC postgres-data et ses données
docker compose down           # Compose ; conserver les volumes
docker compose down -v        # Compose ; effacer les données Postgres / pgAdmin

À la fois helm uninstall et docker compose down -v détruisent les données ; demander d'abord.

Dépannage

Utiliser troubleshooting.md pour les sessions périmées, les défaillances de clé de modèle, les non-concordances d'embedding, les conflits de port, et la configuration partielle de Vault. Rédiger les secrets avant de partager la sortie de commande comme preuve.

Voir aussi

• troubleshooting.md
• runtime-contract.yaml
• nvidia-ontology-query — appeler Auto Ontology une fois qu'il est en cours d'exécution
• nvidia-ontology-management — éditer la couche sémantique
• CLAUDE.md — maintenir Auto Ontology lui-même