Checklist installation serveur client (Aurora Nexus)

Date : 2025-12-23
Objectif : déployer une instance Aurora Nexus mono‑tenant sur un serveur client avec Caddy en reverse proxy, sans exposer Postgres/Qdrant/MinIO/Redis à Internet.

0) Pré‑requis

Ubuntu 22+ (recommandé), accès SSH root/sudo.
Docker Engine 24+ + plugin docker compose.
DNS : enregistrements A/AAAA vers le serveur (UI/API) + domaines MinIO (API + console) si vous exposez MinIO.
Firewall : ports entrants 80/443 ouverts (uniquement).
Un dépôt/artefact de release (images buildables) + accès Git si build sur machine.

1) Sécurité / configuration (avant de lancer)

Générer un .env spécifique au client (ne pas réutiliser dev).
Variables critiques à définir (exemples non exhaustifs) :
- Auth :
  - JWT_SECRET (fort, unique)
  - ALLOW_INSECURE_JWT_SECRET=false
  - OAUTH_LOGIN_CODE_TTL_SECONDS=180 (ou selon politique)
- Gateway interne :
  - GATEWAY_INTERNAL_SECRET (fort, unique)
- BYOK / chiffrement credentials :
  - LLM_CREDENTIALS_ENC_KEY (clé Fernet 32 bytes base64)
  - ALLOW_LEGACY_PLAINTEXT_CREDENTIALS=false
- Postgres/MinIO :
  - POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD
- OAuth Google (si activé MVP) :
  - GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI
- MVP “safe” :
  - ENABLE_INGEST_URL=false (par défaut)
  - AURORA_DIAGNOSTIC_LOG=false (par défaut)
Vérifier l’alignement .env ↔ .env.example (mêmes clés).

2) Réseau & exposition (principe)

Exposer publiquement uniquement Caddy (80/443).
Garder Postgres/Qdrant/MinIO/Redis inaccessibles depuis Internet :
- bind 127.0.0.1 côté hôte (compose)
- pas de règles firewall ouvrant leurs ports
Caddy reverse‑proxy vers 127.0.0.1:<HOST_UI_PORT|HOST_API_PORT|HOST_GATEWAY_PORT>.

3) Déploiement Docker

Depuis la racine du repo :

# 1) Réseau externe (utilisé par la stack si besoin d’interop avec un reverse proxy/stack adjacente)
docker network inspect sylio_default >/dev/null 2>&1 || docker network create sylio_default

# 2) Build + run
docker compose up -d --build

# 3) Bootstrap/migrations DB (idempotent, sans suppression de données)
bash ops/init_db.sh

# 4) État
docker compose ps

4) Installer Caddy (Ubuntu 22+)

Installation recommandée via le dépôt officiel Caddy (service systemd inclus) :

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl gnupg

curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list

sudo apt update
sudo apt install -y caddy
sudo systemctl enable --now caddy

Vérifications :

sudo systemctl status caddy --no-pager
caddy version

5) Configuration Caddyfile (copier/coller, exécutable)

⚠️ Ce fichier est exécutable tel quel si vous utilisez les ports “standards” (wizard) :

UI 3000, API 8000, Gateway 8100
MinIO API 9000, MinIO console 9001

Si vous avez changé les ports dans le wizard / .env, remplacez simplement les numéros 127.0.0.1:<port> ci‑dessous.

Créez / éditez le fichier :

sudo nano /etc/caddy/Caddyfile

Collez (et remplacez seulement les domaines *.example.com par les vôtres) :

rag.example.com {
  encode zstd gzip

  # API (toutes routes /api)
  reverse_proxy /api/* 127.0.0.1:8000

  # Gateway (si exposée)
  handle_path /gateway/* {
    reverse_proxy 127.0.0.1:8100
  }

  # UI (tout le reste)
  reverse_proxy 127.0.0.1:3000

  header {
    # Ajuster selon politique; HSTS uniquement si HTTPS assuré
    -Server
  }
}

minio.example.com {
  encode zstd gzip

  reverse_proxy 127.0.0.1:9000 {
    # Important pour préserver les signatures S3 (URLs pré-signées / uploads).
    header_up Host minio:9000
    header_up X-Forwarded-Proto {scheme}
  }

  header {
    -Server
  }
}

console-minio.example.com {
  encode zstd gzip

  reverse_proxy 127.0.0.1:9001 {
    header_up X-Forwarded-Proto {scheme}
  }

  header {
    -Server
  }
}

Validez et rechargez Caddy :

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

Notes :

La Gateway peut rester accessible uniquement en interne si l’UI/API ne l’exposent pas directement (selon architecture).
Ne pas loguer des querystrings sensibles (OAuth a été modifié pour éviter le JWT dans l’URL).

6) Smoke tests (post‑déploiement)

curl -fsS "http://127.0.0.1:${HOST_API_PORT}/api/health"
curl -fsS "http://127.0.0.1:${HOST_GATEWAY_PORT}/health"
curl -fsS "http://127.0.0.1:${HOST_QDRANT_PORT}/collections"
curl -fsS "http://127.0.0.1:${HOST_MINIO_API_PORT}/minio/health/live"

Recette manuelle MVP :

UI : login admin, navigation pages Admin.
OAuth Google : login, callback, échange code OK.
Ingestion : upload fichier → job terminé → doc consultable.
RAG : requête chat → réponse + citations (sans fuite de chunks si politique activée).
Public links : créer lien public → téléchargement OK + compteur incrémenté.
Feedback : feedback_required force la saisie de feedback.

7) Sauvegardes & rollback (minimum)

Postgres : dump quotidien + test restore (au moins 1 fois avant go‑live).
MinIO : sync/snapshot des buckets uploads/artifacts.
Qdrant : snapshots réguliers + procédure de restauration.
Rollback applicatif : conserver l’ancienne release (images) + procédure de retour arrière (compose + migrations).

Checklist installation serveur client (Aurora Nexus)

On this page