Aurora Nexus — Référence du wizard d'installation

Ce guide décrit l'usage du wizard CLI (ops/install_wizard.py). Il sert de référence commune aux parcours local et serveur.

Avant de lancer le wizard, choisissez le mode :

• Local : docs/02_Installation/Local/01-PreRequis-Local.md
• Serveur / VPS : docs/02_Installation/Serveur/01-PreRequis-Serveur.md

Démarrage one-pass recommandé

Sur un serveur neuf, le point d'entrée recommandé est désormais le wrapper racine :

./install.sh --server --domain nexus.votredomaine.tld --admin-email admin@votredomaine.tld

Pour un poste local Mac/Windows/Linux avec Docker Desktop ou Docker Engine :

./install.sh --local

install.sh ne remplace pas le wizard : il prépare une configuration minimale puis appelle ops/install_wizard.py.

Démarrage avancé via wizard direct

Sur un serveur ou pour une intégration contrôlée, 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 --preset server

1. Prérequis

Voir docs/02_Installation/02-PreRequis.md pour choisir le bon parcours, puis lire les prérequis locaux ou serveur. 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 --preset server

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

python3 ops/install_wizard.py run --preset server --fast

Mode local poste utilisateur :

python3 ops/install_wizard.py run --preset local --fast

Étapes effectuées :

1. Préflight (version Python, docker/docker compose, ports libres).
2. Prompts interactifs (mode serveur/local, domaine ou URLs locales, email admin, ports, stockage objet, 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>.
   • En mode serveur, pour chaque URL avec un sous‑domaine distinct, il demande de confirmer la création de l’entrée DNS A correspondante.
   • En mode local, aucune validation DNS n'est demandée.
   • 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).
   • Mode serveur : OpenRouter runtime, OpenAI embeddings et FreeCurrency restent requis en usage wizard direct.
   • Mode local / install.sh : les clés provider peuvent être différées et configurées ensuite dans l'admin.
   • Stockage objet : minio reste le choix local/dev/autonomie. En mode serveur, aws_s3 peut être choisi pour un client AWS / DSI ; les buckets AWS doivent déjà exister et le wizard ne les crée pas.
   • 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/Serveur/04-Postgres-Externe.md.
7. Init stockage objet :
   • en mode minio, buckets créés via le service one-shot minio-init (idempotent) ;
   • en mode aws_s3, aucun bucket AWS n'est créé par le wizard ; le dry-run vérifie uniquement la cohérence de configuration.
8. Healthcheck HTTP (/api/health).
9. Rapport final (URLs, ports, identifiants masqués) + log JSON lines dans ops/logs/install_wizard_<timestamp>.jsonl.
10. En mode serveur uniquement : génération d’un snippet Caddyfile (caddy.snippet dans le dossier de run) + proposition d’écriture automatique de /etc/caddy/Caddyfile si Caddy est déjà présent et si l'utilisateur confirme.

⚠️ Le wizard ne fait pas apt install caddy. En mode local, Caddy est ignoré. En dry-run, le snippet est généré mais jamais écrit dans /etc/caddy.

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 la machine cible.

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.
• AWS S3 : utiliser --storage-provider aws_s3 ou OBJECT_STORAGE_PROVIDER=aws_s3. Les buckets uploads/artifacts/backups doivent exister, les credentials AWS ne sont jamais affichés en clair, et un rôle IAM runtime peut remplacer les variables AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.

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.