Aurora Nexus — Assistant d'installation

Ce guide décrit l'usage du wizard CLI (ops/install_wizard.py) qui industrialise la mise en service d'Aurora Nexus sur une machine Ubuntu 22+ équipée de Docker 24+.

1. Prérequis

Voir docs/02_Installation/02-PreRequis.md pour la liste complète (logiciels, ports, domaine, clés API).
Le wizard vérifie automatiquement les ports et vous propose des valeurs par défaut si besoin.

Installer les dépendances wizard :

pip install -r ops/requirements.txt

2. Lancer le wizard

python3 ops/install_wizard.py run

Étapes effectuées :

1. Préflight (version Python, docker/docker compose, ports libres).
2. Prompts interactifs (domaine, email admin, ports, secrets Postgres/MinIO, clés API…).
   • Nom de domaine : hostname brut (notebook.auroramind.fr) utilisé côté infra.
   • URL publique : version complète avec protocole (https://notebook.auroramind.fr) utilisée dans les liens et callbacks.
   • JWT dans le body : option “extensions/bots non-web” (si RETURN_JWT_IN_BODY=true).
3. Génération d’un fichier .env dans un dossier de run (par défaut ops/wizard_runs/_runs/<timestamp>/.env), sans toucher au .env racine.
   • Le wizard écrit toutes les variables listées dans .env.example (logs, rétention, GC Qdrant, auth, etc.).
   • Si tu laisses un champ vide, il injecte la valeur par défaut (ou un secret généré aléatoirement pour JWT/DB/MinIO/Gateway/Fernet).
   • Pour écrire explicitement à la racine, fournir --env-path .env (⚠️ à éviter sur un environnement déjà en service).
   • Production : conserver le .env hors repo (ex. /etc/aurora/prod.env, chmod 600) et démarrer avec docker compose --env-file /etc/aurora/prod.env up -d.
4. Création du réseau Docker sylio_default si absent (utile si un reverse-proxy/stack adjacente est jointe à ce réseau).
5. docker compose up -d --build + attente des services (barre de progression Rich).
   • Le wizard lance docker compose avec --env-file <env_path> et injecte aussi AURORA_ENV_FILE=<env_path> pour que les services lisent le bon env.
6. Bootstrap DB uniquement si Postgres est local (POSTGRES_HOST=postgres) :
   • exécution de ops/init_db.sh
   • si Postgres est externe (OVH), aucun bootstrap/migration automatique.
   • guide DB externe : docs/02_Installation/06-Postgres-Externe.md.
7. Init MinIO : buckets créés via le service one-shot minio-init (idempotent).
8. Healthcheck HTTP (/api/health).
9. Rapport final (URLs, ports, identifiants masqués) + log JSON lines dans ops/logs/install_wizard_<timestamp>.jsonl.

3. Options CLI principales

Exemple de stack parallèle (garde l'infra historique intacte) :

COMPOSE_PROJECT_NAME=aurorarag_wizard python3 ops/install_wizard.py run --project-name aurorarag_wizard

Mode rapport uniquement

python3 ops/install_wizard.py report

Relit un .env (par défaut: .env si présent, sinon le dernier run dans ops/wizard_runs/_runs/), teste HOST_API_PORT + HOST_UI_PORT et affiche l'état (succès/erreur) sans toucher aux containers.

4. V1 (post‑MVP) : améliorations prévues

Ces éléments ne sont pas implémentés dans la version actuelle, mais cadrent la V1 “installation/ops” :

• Manifeste de release (public/update-manifest.json) avec version + changelog + hash images.
• Endpoint GET /api/updates/latest qui retourne ce manifeste.
• UI : bannière “Nouvelle version disponible” (Admin → Paramètres) + lien changelog + doc d’upgrade.
• Wizard : option --check-updates pour comparer la version locale au manifeste et proposer un upgrade guidé.
• Packs métiers (option wizard) : sélectionner les packs/services à activer (sources, workspaces, prompts et réglages RAG) lors de l’installation.
• Reset & maintenance : renforcer et tester ops/reset_environment.py (dry-run, garde‑fous, scénarios support) et documenter un runbook d’intervention.

5. Fichier de configuration (--from-file)

Exemple YAML minimal :

app_hostname: rag.mondomaine.com
public_domain: https://rag.mondomaine.com
admin_email: admin@mondomaine.com
host_ports:
  api: 8000
  ui: 3000
  gateway: 8100
  qdrant: 6333
  minio_api: 9000
  minio_console: 9001
  postgres: 5432
  redis: 16379
postgres_user: aurora
postgres_password: super-secret
postgres_db: auroranexus
minio_root_user: aurora-s3
minio_root_password: autre-secret
jwt_secret: change-me
allow_insecure_jwt_secret: false
oauth_login_code_ttl_seconds: 180
llm_credentials_enc_key: change-me
allow_legacy_plaintext_credentials: false
enable_ingest_url: false
aurora_diagnostic_log: false
return_jwt_in_body: false
openai_api_key: sk-proj-xxx
openrouter_api_key: sk-or-yyy
openrouter_usage_api_key: sk-or-usage-zzz
freecurrency_api_url: https://api.freecurrencyapi.com/v1/latest?apikey=XXXX&currencies=EUR

Champs non fournis → valeurs par défaut (cf. ops/install_wizard/models.py).

6. Logs & troubleshooting

• Tous les événements sont tracés dans ops/logs/install_wizard_<timestamp>.jsonl (JSON lines). Idéal pour le support.
• En cas d'échec Docker ou healthcheck, le wizard affiche la commande fautive et l'erreur (docker stderr). Relancer avec --verbose pour les détails.
• Ports occupés → message Ports déjà utilisés: .... Relancer en ajustant les valeurs proposées.
• Secrets jamais ré-affichés en clair (masquage ****abcd).

7. Scripts appelés

• ops/init_db.sh : attend Postgres (aurorarag_postgres), crée la table aurora_schema_migrations, applique aurora_schema.sql + toutes les migrations NN_*.sql (priorité au dossier migrations/, fallback sur la racine si absent). Idempotent, garde une trace par fichier.
• Init MinIO : le wizard repose sur le service minio-init (script ops/init_minio.sh) pour créer les buckets uploads/artifacts/backups. Idempotent.

8. Vérifications post-installation

• Source de vérité : cette section sert de checklist unique (à lier depuis le README).
• UI : http://127.0.0.1:<HOST_UI_PORT> (login admin à créer lors du premier accès).
• API : http://127.0.0.1:<HOST_API_PORT>/api/health → {"status": "ok"}.
• Qdrant : curl http://127.0.0.1:<HOST_QDRANT_PORT>/collections (attend aurora_documents).
• MinIO console : http://127.0.0.1:<HOST_MINIO_CONSOLE_PORT> (credentials choisis).

9. Procédure express pour un nouveau serveur (rappel)

1. Cloner le dépôt public :
   git clone https://github.com/syl2042/Aurora-Nexus.git && cd Aurora-Nexus
2. Lancer le wizard :
   python3 ops/install_wizard.py run
   • renseigne tes clés; si tu laisses vide, les secrets internes sont générés aléatoirement.
   • .env complet est produit (toutes les variables de .env.example).
3. Démarrer :
   docker compose --env-file <chemin/.env> up -d
   (recommandé : déplacer le .env hors repo, ex. /etc/aurora/prod.env, chmod 600).
4. Vérifier /api/health et l’accès UI.

Pour documenter des retours beta, créer une issue Wizard install feedback avec : OS/Docker, options, extrait du log JSON, captures docker compose ps.