Installation via LLM (assistant terminal)

Ce guide permet à un développeur (même débutant) d’installer Aurora Nexus sur un nouveau serveur en s’appuyant sur un LLM capable d’exécuter des commandes dans un terminal.

Exemples d’outils compatibles (non exhaustif) : Codex CLI, Claude Code, Cursor (terminal agent), Aider, Continue, ou tout autre agent équivalent avec accès shell.

⚠️ Repo privé : l’accès nécessite un compte GitHub autorisé.
Demandez au propriétaire du repo les identifiants nécessaires (username + PAT).

Prérequis & installation (avant le prompt)

Le wizard n’installe pas Docker/Compose, Python ou Caddy.
Installez/validez ces prérequis avant d’exécuter le prompt LLM.

DNS (pré‑requis TLS)

Créer des entrées DNS de type A (même IP publique) :

nexus.votredomaine.tld → IP publique du serveur
console-minio.votredomaine.tld → IP publique du serveur
qdrant.votredomaine.tld → IP publique du serveur

Vérifications rapides

uname -a
docker --version
docker compose version
python3 --version
caddy version

Installation Docker + Compose (plugin v2)

sudo apt update
sudo apt install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Installation Caddy

sudo apt install -y caddy

Installation Python via pyenv (recommandé)

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev \
  libsqlite3-dev curl libncursesw5-dev xz-utils tk-dev libxml2-dev libxmlsec1-dev libffi-dev liblzma-dev
curl https://pyenv.run | bash

Activer pyenv (ajouter dans ~/.bashrc ou ~/.profile) :

export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
eval "$(pyenv virtualenv-init -)"

Puis recharger le shell :

exec $SHELL -l

Installer une version compatible et la fixer dans le repo :

pyenv install 3.11.7
cd ~/Apps/Nexus
pyenv local 3.11.7
python --version

Prompt à coller dans votre LLM (une seule fois)

Copiez/collez ce prompt une seule fois dans votre LLM.
Le LLM ne doit pas ré‑afficher ce prompt à chaque étape, il doit simplement l’appliquer.

Tu es un assistant d’installation Aurora Nexus. Règles strictes :

Ne jamais inventer : si une info manque, poser la question.

Toujours demander validation utilisateur avant chaque commande sudo ou toute modification de /etc/*, DNS, reverse‑proxy, firewall.

Ne jamais exposer de secrets (API keys, mots de passe). Masquer dans les logs.

Utiliser uniquement les sources du repo : docs/INSTALL_VIA_LLM.md, .env.example, docker-compose.yml (et GitHub du repo si besoin).

Si un pas échoue, s’arrêter et demander quoi faire.

Questions à poser dès le début :

Domaine public Nexus (ex: nexus.domaine.tld) + IP publique du serveur.

Email admin Nexus.

Clés LLM (OpenRouter runtime + OpenAI embeddings obligatoires).

Clé FreeCurrency (conversion $/€) — obligatoire.

Postgres interne (par défaut) ou externe ?

Caddy déjà installé ? (oui/non)

Plan d’exécution (étapes obligatoires) :

Vérifier prérequis (OS, Docker/Compose, Python via pyenv, Caddy). Proposer l’installation si manquant, avec validation avant sudo.

Vérifier le DNS : dig +short <domaine> A.

Cloner dans ~/Apps/Nexus (créer ~/Apps si absent).

Si repo privé : saisir username/PAT dans le terminal (ne pas coller dans le chat).

Installer les dépendances wizard : pip install -r ops/requirements.txt.

Ubuntu/Debian récents : si externally-managed-environment → sudo python3 -m pip install --break-system-packages -r ops/requirements.txt.

Lancer le wizard : python3 ops/install_wizard.py run --env-path ~/Apps/Nexus/tmp/nexus.env.

Le wizard peut écrire /etc/caddy/Caddyfile (confirmation) et sauvegarde caddy.snippet.

Le wizard peut aussi écrire /etc/aurora/nexus.env avec le bon AURORA_ENV_FILE.

Démarrer : sudo AURORA_ENV_FILE=/etc/aurora/nexus.env docker compose --env-file /etc/aurora/nexus.env up -d --build. 6bis) Appliquer les migrations (Postgres local) :

sudo AURORA_ENV_FILE=/etc/aurora/nexus.env bash ops/init_db.sh 6ter) Vérification migrations (ASSISTANT_CORE présent) :

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\" \ psql -U \"$POSTGRES_USER\" -d \"$POSTGRES_DB\" -tAc \"select code from prompt_template where code='ASSISTANT_CORE';\"'

Caddy (si demandé) : caddy validate puis systemctl reload.

Vérifications :

docker compose ps

curl -f http://127.0.0.1:<HOST_API_PORT>/api/health

curl -f http://127.0.0.1:<HOST_GATEWAY_PORT>/health

curl http://127.0.0.1:<HOST_MINIO_API_PORT>/minio/health/live

curl http://127.0.0.1:<HOST_QDRANT_PORT>/collections

Ouverture UI HTTPS + login admin.

Créer un premier service et ses workspaces.

Résumé final : URLs, ports, chemin env, état des services, next‑steps.

Contraintes :

Interdit d’exécuter des commandes destructrices (rm -rf, purge volumes, etc.) sans accord explicite.

Ne pas redémarrer d’autres stacks/services sans demande.

Si le wizard échoue (mode “reprise LLM”)

Le wizard affiche un bloc “PROMPT LLM (RECOVERY)” en cas d’échec (préflight, validation, docker, healthcheck).
Copiez/collez ce bloc dans votre LLM : il contient les chemins vers le dossier de run, les logs JSONL et les artefacts (ex. caddy.snippet).
⚠️ Ne collez jamais de secrets dans la conversation : le LLM doit lire les fichiers localement sur le serveur.

Contrat de sécurité (à faire respecter par le LLM)

Le LLM doit :

Demander une validation utilisateur avant tout sudo : “Je dois faire X, m’autorisez‑vous ?”.
Ne jamais inventer (si une info manque → poser une question).
Ne jamais afficher de secrets (API keys, mots de passe) dans les logs ou la sortie.
Ne pas modifier DNS / reverse-proxy / firewall sans validation explicite.
S’appuyer sur les sources de vérité du dépôt : docs/INSTALL_VIA_LLM.md, .env.example, docker-compose.yml.
Recommandé : utiliser deux instances LLM (une pour l’analyse, une dédiée aux commandes shell) afin d’éviter les erreurs en cours d’installation.

Variables à collecter (questions au début)

Domaine public Nexus : nexus.votredomaine.tld
Sous‑domaine console MinIO (si utilisé) : console-minio.votredomaine.tld
IP publique du serveur (IPv4)
Email admin Nexus (login UI)
Clés provider LLM (OpenRouter runtime obligatoire + OpenAI embeddings obligatoires)
Clé FreeCurrency (conversion $/€) — obligatoire
Choix : Postgres interne (par défaut) ou externe

Plan d’installation (Postgres interne — recommandé)

1) DNS (pré‑requis TLS)

Créer des entrées DNS de type A (même IP publique) :

nexus.votredomaine.tld → IP publique du serveur
console-minio.votredomaine.tld → IP publique du serveur
qdrant.votredomaine.tld → IP publique du serveur

Vérification (le LLM peut exécuter) :

dig +short nexus.votredomaine.tld A

1bis) Sécurité des secrets (LLM)

Ne pas coller de clés API ou PAT dans la conversation du LLM.
Quand Git demande un username/PAT, saisir directement dans le terminal.
Quand le wizard demande des clés, laisser l’utilisateur taper (le LLM attend).
Si vous utilisez --from-file, créez le fichier localement, puis supprimez‑le après usage.

2) Droits requis (rappel)

Les prérequis et leur installation sont décrits plus haut dans ce guide.
Droits requis (à valider en amont) :

Écriture sur ~/Apps/ (clone du repo).
Écriture sur /etc/aurora/ (env de prod, nécessite sudo).
Écriture sur /etc/caddy/Caddyfile (reverse‑proxy, nécessite sudo).

Si Docker renvoie “permission denied” (socket /var/run/docker.sock) :

ajouter l’utilisateur au groupe docker, ou relancer les commandes docker en sudo.

3) Standardiser l’emplacement du code

On impose :

dossier racine : ~/Apps/
repo : ~/Apps/Nexus/

Commandes :

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

Si le repo est privé, saisir le username/PAT dans le terminal (ne pas le coller dans la discussion LLM).

4) Générer le fichier d’environnement (wizard)

Installer les dépendances wizard :

pip install -r ops/requirements.txt

Note importante (Ubuntu / PEP 668)
Sur Ubuntu/Debian récents, pip global est bloqué par défaut (externally-managed-environment).
Si vous ne voulez pas de venv, utilisez :

sudo python3 -m pip install --break-system-packages -r ops/requirements.txt

Si un paquet Debian bloque la mise à jour (ex: typing-extensions), relancer avec :

sudo python3 -m pip install --break-system-packages --ignore-installed -r ops/requirements.txt

Note : le wizard pose des questions sur les ports et les paramètres Docling.
Si vous n’avez pas de contrainte particulière, gardez les valeurs par défaut (ces paramètres sont modifiables ensuite via l’UI d’admin).

Qdrant hybride
Par défaut, le wizard active le mode hybride (vecteur dense nommé dense).
Si vous désactivez ce mode, QDRANT_DENSE_VECTOR_NAME est laissé vide.
⚠️ Changer ce choix après ingestion implique de recréer Qdrant et de ré‑ingérer les documents.

Option avancée (recommandée pour “cloner” votre instance actuelle) :

Placez un seed idempotent dans ops/seed/current.sql (prompts/services/workspaces/paramètres, y compris system_settings).
Le wizard l’appliquera automatiquement après init_db.sh si le fichier n’est pas vide.

Générer un env (en espace utilisateur, sans sudo) :

mkdir -p ~/Apps/Nexus/tmp
python3 ops/install_wizard.py run --env-path ~/Apps/Nexus/tmp/nexus.env

Le wizard génère aussi un caddy.snippet (dans le dossier de run) et peut proposer d’écrire /etc/caddy/Caddyfile avec confirmation.

Puis placer l’env en “prod” (hors repo) :

sudo mkdir -p /etc/aurora
sudo install -m 600 ~/Apps/Nexus/tmp/nexus.env /etc/aurora/nexus.env

Important : le fichier doit contenir :

AURORA_ENV_FILE=/etc/aurora/nexus.env

Note : /etc/aurora/nexus.env est la source de vérité des secrets en production.
Si un ancien fichier (ex. nexus.env.full) contient change-me-now, fiez-vous à /etc/aurora/nexus.env.

Mot de passe admin :

Le wizard le demande. Si vous laissez vide, il est généré et écrit dans nexus.env.full.

Vérification rapide (sur le serveur) :

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

Si le wizard a écrit un autre chemin (ex: ~/Apps/Nexus/tmp/nexus.env), corriger :

sudo sed -i 's|^AURORA_ENV_FILE=.*$|AURORA_ENV_FILE=/etc/aurora/nexus.env|' /etc/aurora/nexus.env

5) Démarrer la stack

Depuis ~/Apps/Nexus :

docker compose --env-file /etc/aurora/nexus.env up -d --build

5bis) Appliquer les migrations (Postgres local)

sudo AURORA_ENV_FILE=/etc/aurora/nexus.env bash ops/init_db.sh

5ter) Vérifier que les seeds prompts sont présents

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" \
  psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -tAc "select code from prompt_template where code='ASSISTANT_CORE';"'

Si la commande ne retourne rien, relancer bash ops/init_db.sh.

6) Vérifications après démarrage

docker compose --env-file /etc/aurora/nexus.env ps
curl -f http://127.0.0.1:$(grep -E '^HOST_API_PORT=' /etc/aurora/nexus.env | cut -d= -f2)/api/health
curl -f http://127.0.0.1:$(grep -E '^HOST_GATEWAY_PORT=' /etc/aurora/nexus.env | cut -d= -f2)/health
curl http://127.0.0.1:$(grep -E '^HOST_MINIO_API_PORT=' /etc/aurora/nexus.env | cut -d= -f2)/minio/health/live
curl http://127.0.0.1:$(grep -E '^HOST_QDRANT_PORT=' /etc/aurora/nexus.env | cut -d= -f2)/collections

Puis :

Ouvrir l’UI HTTPS, se connecter en admin.
Créer un premier service puis les workspaces associés.
Assistant RAG (optionnel) : ouvrir /{locale}/admin/assistant-rag et cliquer Rafraîchir la base (peuple __rag_assistant pour stabiliser les recommandations).

6bis) Si session LLM interrompue

Si la session expire pendant le wizard :

Relancer simplement :
python3 ops/install_wizard.py run --env-path ~/Apps/Nexus/tmp/nexus.env
Ou relancer avec --from-file si vous avez déjà un fichier de config.

Reverse-proxy (Caddy) + HTTPS

Rappels importants :

Le LLM ne modifie pas /etc/caddy/Caddyfile sans validation utilisateur.
TLS automatique (Let’s Encrypt) nécessite que nexus.votredomaine.tld pointe déjà vers le serveur (DNS OK) et que le port 443 soit accessible.

Bloc Caddy complet (adapter les ports si besoin) :

nexus.votredomaine.tld {
    encode gzip
    tls admin@votredomaine.tld

    @minio_buckets path_regexp ^/(aurorarag-uploads|aurorarag-artifacts|aurorarag-backups)($|/.*)
    handle @minio_buckets {
        reverse_proxy 127.0.0.1:9000 {
            header_up Host {http.request.host}
            header_up X-Forwarded-Proto {scheme}
            header_up X-Forwarded-Host {http.request.host}
            transport http {
                read_buffer 64MB
                write_buffer 64MB
            }
        }
    }

    @api path_regexp api ^/(api|docs|openapi\\.json)($|/.*)
    handle @api {
        reverse_proxy 127.0.0.1:8000
    }

    handle {
        reverse_proxy 127.0.0.1:3000
    }
}

console-minio.votredomaine.tld {
    encode gzip
    tls admin@votredomaine.tld

    reverse_proxy 127.0.0.1:9001
}

qdrant.votredomaine.tld {
    encode gzip
    tls admin@votredomaine.tld

    reverse_proxy 127.0.0.1:6333
}

Validation / reload (avec validation utilisateur avant sudo) :

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

Cas Postgres externe

Si Postgres n’est pas le conteneur docker interne, appliquer le schéma + migrations avant de démarrer l’API :

docs/02_Installation/06-Postgres-Externe.md

Installation manuelle (sans LLM)

À utiliser si l’installation via LLM devient trop complexe.
Objectif : arriver jusqu’au test en URL publique (HTTPS).

0) Prérequis (obligatoires)

DNS (pré‑requis TLS) :
nexus.votredomaine.tld, console-minio.votredomaine.tld, qdrant.votredomaine.tld → IP publique.

Reprenez les commandes de la section Prérequis & installation (avant le prompt) pour :

Docker + Docker Compose (plugin v2)
Caddy
Python via pyenv (recommandé)

Vérifier :

docker --version
docker compose version
python3 --version
caddy version

1) DNS

Créer une entrée A :

nexus.votredomaine.tld → IP publique du serveur

Optionnel :

console-minio.votredomaine.tld → même IP
qdrant.votredomaine.tld → même IP (si exposition publique)

Vérifier :

dig +short nexus.votredomaine.tld A

2) Cloner le repo

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

Si vous avez déjà cloné le repo (installation interrompue / relance), mettez-le à jour :

cd ~/Apps/Nexus
git pull

3) Installer les dépendances du wizard

pip install -r ops/requirements.txt

Si externally-managed-environment :

sudo python3 -m pip install --break-system-packages -r ops/requirements.txt

4) Générer l’env via le wizard

mkdir -p ~/Apps/Nexus/tmp
python3 ops/install_wizard.py run --env-path ~/Apps/Nexus/tmp/nexus.env

Puis placer l’env en prod :

sudo mkdir -p /etc/aurora
sudo install -m 600 ~/Apps/Nexus/tmp/nexus.env /etc/aurora/nexus.env

Vérifier :

grep '^AURORA_ENV_FILE=' /etc/aurora/nexus.env

5) Démarrer

docker compose --env-file /etc/aurora/nexus.env up -d --build

6) Configurer Caddy (si pas fait par le wizard)

Suivre : docs/02_Installation/04-Checklist-Client.md
Puis :

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy

7) Tests (URL publique)

curl -f https://nexus.votredomaine.tld/api/health

Ensuite :

Ouvrir l’UI HTTPS
Se connecter en admin
Créer un premier service + workspaces

Troubleshooting (one-pass)

Warnings “variable is not set” quand vous lancez `docker compose`

Cause : vous exécutez docker compose sans charger l’env de prod.

Solution : toujours utiliser :

sudo docker compose --env-file /etc/aurora/nexus.env ps
sudo docker compose --env-file /etc/aurora/nexus.env up -d --build

Symptôme : le login appelle l’API mais Caddy renvoie 502.
Cause fréquente : l’API est en boucle de restart (ex: ModuleNotFoundError: No module named 'ops').

Correctif :

sudo docker compose --env-file /etc/aurora/nexus.env logs --tail=200 api
sudo docker compose --env-file /etc/aurora/nexus.env up -d --build --force-recreate api api_worker

Si l’erreur persiste : vérifiez que vous êtes bien sur la dernière version du repo (le build api doit inclure ops/install_wizard).

Test streaming SSE renvoie 401 en CLI

Cause : endpoint protégé (JWT/cookie requis).
Solution : testez depuis l’UI (DevTools → Network) ou fournissez un vrai token Authorization: Bearer ....

Installation via LLM (assistant terminal)

On this page