Aurora NexusInstallation

Guide de test local — Aurora Nexus

(depuis `TEST_LOCAL.md`)

Ce document décrit comment tester l'application en local pour le développement et le débogage.

Conventions (ports / URLs)

Selon votre mode d’exécution, les ports diffèrent :

Mode dev (API/UI lancées à la main) : API http://localhost:8000 et UI http://localhost:3000.
Mode Docker (stack complète via .env.example) : ports “non‑standards” (par défaut UI 13500, API 18500, Qdrant 16500, MinIO 19500/19501, …).

Dans ce guide, beaucoup d’exemples curl utilisent http://localhost:8000 (mode dev). Si vous utilisez Docker, remplacez l’URL par http://127.0.0.1:${HOST_API_PORT}.

Table des matières

Prérequis
Démarrage des services
Variables d'environnement
Tests backend
Tests frontend
Débogage des connexions
Débogage Qdrant
Débogage MinIO
Débogage PostgreSQL
Débogage des embeddings
Débogage du RAG
Débogage des documents
Débogage des requêtes
Débogage de l'authentification
Débogage de l'admin
Débogage des clés API
Débogage des performances
Débogage des erreurs fréquentes
Logs et monitoring
Nettoyage

Prérequis

Docker Desktop installé et démarré
Node.js 18+ installé
Python 3.11+ installé
psql installé (PostgreSQL client)
mc installé (MinIO client)

Vérification des prérequis

# Vérifier Docker
docker --version
docker compose version

# Vérifier Node.js
node --version
npm --version

# Vérifier Python
python3 --version

# Vérifier PostgreSQL client
psql --version

# Vérifier MinIO client
mc --version

Démarrage des services

Démarrer tous les services

# Depuis la racine du projet
docker compose up -d --build

# Vérifier que tous les services sont démarrés
docker compose ps

URLs (selon votre .env) :

UI : http://127.0.0.1:${HOST_UI_PORT}
API : http://127.0.0.1:${HOST_API_PORT}
Swagger : http://127.0.0.1:${HOST_API_PORT}/api/docs

Démarrer un service spécifique

# Démarrer PostgreSQL seulement
docker compose up -d postgres

# Démarrer Qdrant seulement
docker compose up -d qdrant

# Démarrer MinIO seulement
docker compose up -d minio

Arrêter les services

# Arrêter tous les services
docker compose down

# Arrêter un service spécifique
docker compose stop postgres

# Arrêter et supprimer les volumes (⚠️ PERD TOUTES LES DONNÉES)
docker compose down -v

Variables d'environnement

Fichier .env

Créer .env à la racine du projet (utilisé par docker compose via env_file: .env).

Notes :

Le wizard CLI peut aussi générer un fichier .env dans un dossier de run (ex: ops/wizard_runs/_runs/<timestamp>/.env) sans toucher au .env racine.
Pour lancer Docker avec un autre fichier d’environnement, utilisez docker compose --env-file <path> up -d (et/ou AURORA_ENV_FILE selon le docker-compose.yml).

# PostgreSQL (exemple local)
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_DB=auroranexus
POSTGRES_USER=aurora
POSTGRES_PASSWORD=change-me-now
DATABASE_URL=postgresql://aurora:change-me-now@postgres:5432/auroranexus

# Qdrant
QDRANT_URL=http://qdrant:6333

# MinIO
MINIO_ROOT_USER=aurora-minio
MINIO_ROOT_PASSWORD=change-me-now  # >= 8 caractères
S3_ENDPOINT=http://minio:9000
S3_BUCKET_UPLOADS=aurorarag-uploads
S3_BUCKET_ARTIFACTS=aurorarag-artifacts

# API Keys (valeurs de test)
OPENAI_API_KEY=sk-test-openai-key-1234567890
OPENROUTER_API_KEY=sk-or-test-key-1234567890

# Chiffrement BYOK (doit rester stable)
# Générer une clé Fernet (base64 url-safe, 32 bytes) :
#   python3 -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"
LLM_CREDENTIALS_ENC_KEY=PASTE_A_FERNET_KEY_HERE

# URLs
# - Mode dev : http://localhost:8000
# - Mode Docker (stack complète) : http://127.0.0.1:${HOST_API_PORT:-18500}
NEXT_PUBLIC_API_URL=http://127.0.0.1:${HOST_API_PORT:-18500}

Notes importantes :

En production/multi-tenant, la clé OpenRouter utilisée par le runtime est généralement stockée en base via l’UI Admin (Providers → Credentials). Voir TROUBLESHOOTING.md.
ADMIN_EMAIL / ADMIN_DEFAULT_PASSWORD servent au seed initial (si l’utilisateur n’existe pas en DB).

Tests backend

Démarrer le backend en développement

Note : inutile si vous utilisez la stack Docker complète (service api).

cd api
python3 -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate     # Windows

pip install -r requirements.txt
uvicorn main:app --reload --host 0.0.0.0 --port 8000

Tester l'API avec curl

# Test de santé
curl http://localhost:8000/api/health

# Test d'authentification
curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "Admin123!"}'

# Test de l'API admin (nécessite token)
curl -H "Authorization: Bearer VOTRE_TOKEN" \
  http://localhost:8000/api/admin/stats

Exécuter les migrations

Aurora Nexus versionne le schéma complet dans aurora_schema.sql. Pour aligner une base locale :

# Applique le schéma + seeds de base (recommandé en local)
bash ops/init_db.sh

Tests frontend

Démarrer le frontend en développement

cd ui
npm install
npm run dev

Accéder à l'application

Mode dev (API/UI locales) :

Frontend : http://localhost:3000
Backend API : http://localhost:8000
Swagger UI : http://localhost:8000/api/docs

Mode Docker (stack complète) :

Frontend : http://127.0.0.1:${HOST_UI_PORT}
Backend API : http://127.0.0.1:${HOST_API_PORT}
Swagger UI : http://127.0.0.1:${HOST_API_PORT}/api/docs
Qdrant Dashboard : http://127.0.0.1:${HOST_QDRANT_PORT}/dashboard
MinIO Console : http://127.0.0.1:${HOST_MINIO_CONSOLE_PORT}

Débogage des connexions

Vérifier les connexions réseau

# Vérifier que PostgreSQL écoute
telnet localhost ${POSTGRES_HOST_PORT:-5432}

# Vérifier que Qdrant écoute
telnet localhost ${HOST_QDRANT_PORT:-6333}

# Vérifier que MinIO écoute
telnet localhost ${HOST_MINIO_API_PORT:-9000}

# Vérifier que le backend écoute
telnet localhost ${HOST_API_PORT:-8000}

# Vérifier que le frontend écoute
telnet localhost ${HOST_UI_PORT:-3000}

Vérifier les variables d'environnement

# Dans le backend
printenv | grep POSTGRES
printenv | grep QDRANT
printenv | grep MINIO

# Dans le frontend
printenv | grep NEXT_PUBLIC

Débogage Qdrant

Accéder au dashboard Qdrant

http://localhost:6333/dashboard

Vérifier l'état du cluster

curl http://localhost:6333

Lister les collections

curl http://localhost:6333/collections

Vérifier une collection spécifique

curl http://localhost:6333/collections/documents

Recréer une collection (en cas de corruption)

# Supprimer la collection
curl -X DELETE http://localhost:6333/collections/documents

# Recréer avec le schéma approprié (voir api/main.py)
curl -X PUT http://localhost:6333/collections/documents \
  -H "Content-Type: application/json" \
  -d '{
    "vectors": {
      "size": 1536,
      "distance": "Cosine"
    }
  }'

Débogage MinIO

Accéder à la console MinIO

http://localhost:9001

User: minioadmin
Password: minioadmin

Vérifier les buckets

# Lister les buckets
mc ls local/

# Créer un bucket (si nécessaire)
mc mb local/documents

# Donner les permissions publiques (⚠️ DEV SEULEMENT)
mc anonymous set public local/documents

Vérifier les fichiers

# Lister les fichiers dans un bucket
mc ls local/documents/

# Télécharger un fichier pour inspection
mc cp local/documents/document-id.pdf ./test.pdf

Débogage PostgreSQL

Se connecter à PostgreSQL

psql -h localhost -p 5432 -U postgres -d aurora_rag

Vérifier les tables

-- Lister toutes les tables
\dt

-- Vérifier la table users
SELECT * FROM users LIMIT 5;

-- Vérifier la table documents
SELECT * FROM documents LIMIT 5;

-- Vérifier la table queries_log
SELECT * FROM queries_log LIMIT 5;

Réinitialiser les données (⚠️ PERD TOUTES LES DONNÉES)

-- Supprimer toutes les données
DELETE FROM queries_log;
DELETE FROM documents;
DELETE FROM user_sessions;
DELETE FROM user_permissions;
DELETE FROM users;

-- Réinitialiser les séquences
SELECT setval('users_id_seq', 1, false);

Débogage des embeddings

Tester la génération d'embeddings

# Via l'API backend
curl -X POST http://localhost:8000/api/test/embeddings \
  -H "Content-Type: application/json" \
  -d '{"text": "Test de génération d embeddings"}'

Vérifier les modèles disponibles

# Pour OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer VOTRE_OPENAI_KEY"

# Pour OpenRouter
curl https://openrouter.ai/api/v1/models \
  -H "Authorization: Bearer VOTRE_OPENROUTER_KEY"

Débogage du RAG

Tester une requête RAG complète

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Quelle est la procédure pour les congés annuels ?",
    "user_email": "test@example.com"
  }'

Vérifier les paramètres RAG

curl -H "Authorization: Bearer VOTRE_TOKEN" \
  http://localhost:8000/api/admin/settings?category=rag

Débogage des documents

Ingérer un document de test

curl -X POST http://localhost:8000/api/ingest/url \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/document.pdf",
    "source_app": "test"
  }'

Vérifier les documents indexés

curl -H "Authorization: Bearer VOTRE_TOKEN" \
  http://localhost:8000/api/admin/documents

Débogage des requêtes

Vérifier l'historique des requêtes

curl -H "Authorization: Bearer VOTRE_TOKEN" \
  http://localhost:8000/api/admin/queries

Tester une requête spécifique

curl -X POST http://localhost:8000/api/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Question de test",
    "user_email": "test@example.com"
  }'

Débogage de l'authentification

Créer un utilisateur de test

-- Dans PostgreSQL
INSERT INTO users (email, password_hash, full_name, role, is_active)
VALUES (
  'test@example.com',
  '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewdBPj/RK.PZvO.S',
  'Utilisateur Test',
  'user',
  true
);

Tester la connexion

curl -X POST http://localhost:8000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com", "password": "Test123!"}'

Débogage de l'admin

Accéder à l'interface admin

http://localhost:3000/admin

Vérifier les permissions

curl -H "Authorization: Bearer TOKEN_ADMIN" \
  http://localhost:8000/api/admin/users

Tester la création d'utilisateur

curl -X POST http://localhost:8000/api/admin/users \
  -H "Authorization: Bearer TOKEN_ADMIN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "password": "NewUser123!",
    "full_name": "Nouvel Utilisateur",
    "role": "user",
    "permissions": []
  }'

Débogage des clés API

Tester une clé API

curl "http://localhost:8000/api/ai/test-key?provider=openai&api_key=sk-test-key"

Vérifier les clés dans les paramètres

curl -H "Authorization: Bearer TOKEN_ADMIN" \
  http://localhost:8000/api/admin/settings?category=ai_models

Débogage des performances

Monitorer les ressources Docker

# Voir l'utilisation CPU/mémoire
docker stats

# Voir les logs en temps réel
docker compose logs -f

# Voir les logs d'un service spécifique
docker compose logs -f api

Profiler les requêtes lentes

-- Dans PostgreSQL, trouver les requêtes lentes
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

Débogage des erreurs fréquentes

Erreur: "Connection refused"

Vérifier que le service est démarré : docker compose ps
Vérifier les ports : docker compose logs SERVICE
Vérifier le firewall

Erreur: "Authentication failed"

Vérifier les variables d'environnement
Vérifier les identifiants dans .env
Réinitialiser les mots de passe si nécessaire

Erreur: "Embedding generation failed"

Vérifier la clé API
Vérifier la connectivité Internet
Vérifier les quotas API

Erreur: "Document not found in storage"

Vérifier que MinIO est démarré
Vérifier les permissions du bucket
Vérifier l'URL du document

Logs et monitoring

Logs backend

# Logs en temps réel
docker compose logs -f api

# Logs des dernières heures
docker compose logs --since 1h api

Logs frontend

# Dans le terminal de développement Next.js
# Les logs s'affichent automatiquement

Logs PostgreSQL

docker compose logs -f postgres

Logs Qdrant

docker compose logs -f qdrant

Logs MinIO

docker compose logs -f minio

Nettoyage

Nettoyer les containers Docker

# Stopper et supprimer tous les containers
docker compose down

# Supprimer les images non utilisées
docker image prune

# Supprimer les volumes non utilisés (⚠️ PERD TOUTES LES DONNÉES)
docker volume prune

Nettoyer les dépendances

# Backend
cd api
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend
cd ui
rm -rf node_modules
npm install

Réinitialiser complètement

# ⚠️ PERD TOUTES LES DONNÉES
docker compose down -v
docker volume prune -f
docker image prune -f

# Recréer depuis zéro
docker compose up -d

Checklist de test

Ressources supplémentaires

Documentation API : http://localhost:8000/api/docs (dev) ou http://127.0.0.1:${HOST_API_PORT:-18500}/api/docs (Docker)
Qdrant Dashboard : http://localhost:6333/dashboard (dev) ou http://127.0.0.1:${HOST_QDRANT_PORT:-16500}/dashboard (Docker)
MinIO Console : http://localhost:9001 (dev) ou http://127.0.0.1:${HOST_MINIO_CONSOLE_PORT:-19501} (Docker)
PostgreSQL : psql -h localhost -p ${POSTGRES_HOST_PORT:-5432} -U ${POSTGRES_USER:-aurora} -d ${POSTGRES_DB:-auroranexus}

Checklist installation serveur client (Aurora Nexus)

(depuis `CHECKLIST_INSTALLATION_SERVEUR_CLIENT.md`)

Postgres externe (installation / bootstrap)

bootstrap/migrations quand Postgres est externe

On this page

Conventions (ports / URLs)Table des matières Prérequis Vérification des prérequis Démarrage des services Démarrer tous les services Démarrer un service spécifique Arrêter les services Variables d'environnement Fichier .env Tests backend Démarrer le backend en développement Tester l'API avec curl Exécuter les migrations Tests frontend Démarrer le frontend en développement Accéder à l'application Débogage des connexions Vérifier les connexions réseau Vérifier les variables d'environnement Débogage Qdrant Accéder au dashboard Qdrant Vérifier l'état du cluster Lister les collections Vérifier une collection spécifique Recréer une collection (en cas de corruption)Débogage MinIO Accéder à la console MinIO Vérifier les buckets Vérifier les fichiers Débogage PostgreSQL Se connecter à PostgreSQL Vérifier les tables Réinitialiser les données (⚠️ PERD TOUTES LES DONNÉES)Débogage des embeddings Tester la génération d'embeddings Vérifier les modèles disponibles Débogage du RAG Tester une requête RAG complète Vérifier les paramètres RAG Débogage des documents Ingérer un document de test Vérifier les documents indexés Débogage des requêtes Vérifier l'historique des requêtes Tester une requête spécifique Débogage de l'authentification Créer un utilisateur de test Tester la connexion Débogage de l'admin Accéder à l'interface admin Vérifier les permissions Tester la création d'utilisateur Débogage des clés API Tester une clé API Vérifier les clés dans les paramètres Débogage des performances Monitorer les ressources Docker Profiler les requêtes lentes Débogage des erreurs fréquentes Erreur: "Connection refused"Erreur: "Authentication failed"Erreur: "Embedding generation failed"Erreur: "Document not found in storage"Logs et monitoring Logs backend Logs frontend Logs PostgreSQL Logs Qdrant Logs MinIO Nettoyage Nettoyer les containers Docker Nettoyer les dépendances Réinitialiser complètement Checklist de test Ressources supplémentaires