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

Démarrage sur un serveur (ordre recommandé)

Sur un serveur neuf, commencez par cloner le repo, puis lancez le wizard depuis ce dossier :

mkdir -p ~/Apps
cd ~/Apps
git clone https://github.com/syl2042/Aurora-Nexus.git Nexus
cd ~/Apps/Nexus

pip install -r ops/requirements.txt
python3 ops/install_wizard.py run

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

Si vous lancez le wizard sans dépendances, il proposera de les installer automatiquement.

2. Lancer le wizard

python3 ops/install_wizard.py run

Mode rapide (garde ports & Docling par défaut) :

python3 ops/install_wizard.py run --fast

É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 (nexus.votredomaine.tld) utilisé côté infra.
   • URL publique : version complète avec protocole (https://nexus.votredomaine.tld) utilisée dans les liens et callbacks.
   • URLs dérivées : le wizard propose automatiquement console-minio.<domaine>, PUBLIC_UPLOAD_BASE_URL (ex: https://<domaine>/minio) et, si souhaité, qdrant.<domaine>.
   • Pour chaque URL avec un sous‑domaine distinct, il demande de confirmer la création de l’entrée DNS A correspondante.
   • Aurora Scraper (optionnel) : le wizard demande si Scraper est installé. Si oui, il demande son URL (stockée dans NEXT_PUBLIC_AURORA_SCRAPER_URL) pour afficher un bouton “Ouvrir Scraper” dans l’UI Nexus.
   • JWT dans le body : option “extensions/bots non-web” (si RETURN_JWT_IN_BODY=true).
   • OpenRouter runtime obligatoire.
   • OpenAI embeddings obligatoire.
   • OpenRouter Usage : optionnel (laisser vide si non utilisé).
   • FreeCurrency obligatoire pour la conversion $/€.
   • Qdrant hybride : recommandé (par défaut). Si désactivé, QDRANT_DENSE_VECTOR_NAME est vidé. Changer ce choix après ingestion impose une recréation Qdrant + ré‑ingestion.
   • Mot de passe admin (seed) : si laissé vide, le wizard génère un mot de passe et l’écrit dans nexus.env.full.
   • Mode --from-file : pensez à fournir admin_default_password si vous voulez un mot de passe spécifique (sinon il est généré).
   • Les questions ports et Docling peuvent rester sur les valeurs par défaut (modifiables ensuite via l’UI d’admin).
   • Si docker renvoie “permission denied”, le wizard propose de relancer les commandes docker en sudo. Alternative : ajouter l’utilisateur au groupe docker puis relancer (sudo usermod -aG docker $USER + logout/login).
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 (le fichier doit contenir AURORA_ENV_FILE=/etc/aurora/prod.env).
   • Le wizard génère aussi un fichier complet avec secrets visibles à la racine (nexus.env.full) et demande de le copier dans un endroit sûr.
     • Si nexus.env.full contient encore change-me-now, c’est que la valeur n’a pas été fournie/générée au moment du wizard : la source de vérité est alors /etc/aurora/nexus.env.
     • Vérification rapide (sur le serveur) :

       sudo rg '^(ADMIN_EMAIL|ADMIN_DEFAULT_PASSWORD|POSTGRES_USER|POSTGRES_PASSWORD)=' /etc/aurora/nexus.env

   • Le wizard peut écrire une copie de production (par défaut /etc/aurora/nexus.env) avec le bon AURORA_ENV_FILE.
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 ops/seed/current.sql est présent et non vide, il est appliqué (seed des prompts/services/workspaces/paramètres actuels).
   • vérification automatique : toutes migrations + présence de ASSISTANT_CORE (sinon le wizard échoue).
   • 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.
10. Génération d’un snippet Caddyfile (caddy.snippet dans le dossier de run) + proposition d’écriture automatique de /etc/caddy/Caddyfile (avec confirmation).

⚠️ Le wizard peut écrire /etc/caddy/Caddyfile si vous confirmez. Sinon, utilisez le fichier caddy.snippet (cf. docs/02_Installation/04-Checklist-Client.md).

4. Après installation (premiers pas)

1. Ouvrir le domaine public dans un navigateur (HTTPS) et se connecter avec l’admin.
2. Vérifier les paramètres essentiels (admin → paramètres) :
   • Provider LLM + clés (OpenRouter/OpenAI).
   • Embeddings, chunking, limites d’upload.
3. Créer un premier service puis ses workspaces (obligatoire pour l’ingestion et les requêtes).
4. Tester /api/health et l’UI.
5. Assistant RAG (optionnel) : aller sur /{locale}/admin/assistant-rag et cliquer Rafraîchir la base (peuple la KB interne __rag_assistant).

4bis. Seed “config actuelle” (optionnel)

Objectif : injecter vos prompts/services/workspaces/paramètres dans les prochaines installations.
Le wizard applique automatiquement ops/seed/current.sql s’il est présent et non vide.

Tables recommandées :

• prompt_template, prompt_version, prompt_binding
• service_profiles
• caller_apps_config
• source_apps_config, workspaces_config
• cache_settings
• optimizer_settings
• llm_providers, tenant_allowed_providers (si vous voulez figer l’onglet “Providers”)
• system_settings

Export minimal (à lancer sur l’instance source) :

sudo bash -lc 'set -a; source /etc/aurora/nexus.env; set +a; \
POSTGRES_CONTAINER=$(docker compose ps -q postgres); \
docker exec -i "$POSTGRES_CONTAINER" env PGPASSWORD="$POSTGRES_PASSWORD" \
  pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
  --data-only --inserts \
  -t prompt_template -t prompt_version -t prompt_binding \
  -t service_profiles \
  -t caller_apps_config \
  -t source_apps_config -t workspaces_config \
  -t cache_settings -t optimizer_settings \
  -t llm_providers -t tenant_allowed_providers \
  -t system_settings \
  > ops/seed/current.sql'

⚠️ Rendez le seed idempotent (ON CONFLICT / UPDATE) si vous comptez relancer le wizard.

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

3bis. Alternative : page web “Installation” (dry-run)

Si vous avez déjà une instance Nexus en cours (même partielle), la page /<locale>/installation permet de générer :

• un env.preview.env (secrets masqués),
• un plan.json (liste des services et étapes).

Techniquement, la page appelle POST /api/public/installation/dry-run et peut être protégée par INSTALLATION_WIZARD_TOKEN (header X-Installation-Token).

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: nexus.votredomaine.tld
public_domain: https://nexus.votredomaine.tld
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
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).

Mode “reprise par LLM” (en cas d’échec)
Si le wizard échoue (préflight, validation, docker, healthcheck), il affiche un bloc “PROMPT LLM (RECOVERY)” à coller dans un LLM.
Ce prompt contient :

• le dossier de run (ex. ops/wizard_runs/_runs/<timestamp>/)
• le log JSONL associé (ex. ops/logs/install_wizard_<timestamp>.jsonl)
• les artefacts utiles (caddy.snippet, .env, etc.)

Ne collez jamais de secrets dans le chat : le LLM doit lire les fichiers locaux depuis le serveur.

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
   (si le .env est hors repo, vérifier que le fichier contient bien AURORA_ENV_FILE=<chemin/.env>).
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.