RAGatm Open

Installation

Le déploiement de référence s’appelle Compact : une machine, Docker Compose, neuf services, trois modèles téléchargés une fois puis exécutés hors ligne. Les commandes ci-dessous sont celles publiées dans les dépôts.

Prérequis matériels et logiciels

Machine qualifiée pour le profil Compact (CPU).

Machine qualifiée
x86_64, 8 threads, 14 Go de RAM, sans GPU
Mémoire
≈ 8 Go utilisés en charge (reranker ≈ 3,8 Go, Ollama ≈ 2 Go, Django/Celery ≈ 1,5 Go) ; le préflight avertit sous 9 Go disponibles.
Disque
≈ 3 Go d’images + ≈ 4 Go de modèles + données ; le préflight avertit sous 12 Go libres.
Système et outils
Linux x86_64, Docker ≥ 24 avec Compose v2, openssl.
Internet
Nécessaire uniquement pendant la construction des images et l’approvisionnement des modèles ; aucune sortie en fonctionnement nominal.
GPU
Aucun GPU requis. Les profils GPU 8 Go et 12 Go sont décrits mais non qualifiés.

Profils matériels

Compact (CPU)

Testé

8 threads, 14 Go RAM, sans GPU

Une machine, 9 services Docker Compose, modèles locaux sur CPU. Déploiement de référence, qualification fonctionnelle exécutée (dossier interne non distribué).

Compact + GPU 8 Go

À qualifier

GPU 8 Go dédié

Même modèle 1,5 B sur un GPU de 8 Go. Décrit dans le registre de la passerelle, verdict NOT_EXECUTED dans la documentation Compact.

Compact + GPU 12 Go

À qualifier

GPU 12 Go, pilotes NVIDIA + NVIDIA Container Toolkit

Modèle qwen2.5:7b-instruct via compose.gpu-12gb.yml. Décrit mais non qualifié : aucun digest enregistré, aucune mesure.

Modèles téléchargés (aucun poids distribué par le projet)

Registre Compact des modèles
RôleModèleRuntimeLicenceTailleCompact
Embeddings (768 dimensions, FR/EN)granite-embedding:278mOllamaApache-2.0≈ 0,6 GBinstallé
Génération, profil CPU (défaut Compact)qwen2.5:1.5b-instruct (Q4_K_M)OllamaApache-2.0≈ 1 GBinstallé
Reranking cross-encoder (64 passages max par requête)BAAI/bge-reranker-v2-m3TEIApache-2.0≈ 2,3 GB (float32)installé
Génération, profil GPU 12 Go (décrit, non qualifié)qwen2.5:7b-instructOllamaApache-2.0≈ 4,7 GBnon installé

Étapes

Treize étapes, de la vérification des prérequis au premier compte. Les étapes marquées « déduit » sont une lecture de la documentation, pas une citation.

  1. Vérifier les prérequis : Linux x86_64, Docker ≥ 24 + Compose v2, 14 Go RAM (≥ 10 Go disponibles recommandés), ~7 Go de disque (images + modèles) + données, pas de GPU requis, accès Internet uniquement pour l’approvisionnement.

    Source : compact/docs/installation.md lignes 3-19

  2. Cloner les deux dépôts côte à côte : git clone https://github.com/ragatm-open/ragatm-open.git puis git clone https://github.com/ragatm-open/ai-gateway-open.git (requis, placé à côté de ragatm-open/). Le Pool n’est pas requis.

    Source : README.md lignes 35-40; compact/docs/installation.md lignes 28-31

  3. Préflight : cd ragatm-open/compact && scripts/preflight.sh (Docker/Compose, RAM, disque, port 127.0.0.1:18080, .env, valeurs de démonstration). Attendre PREFLIGHT=PASS.

    Source : README.md ligne 37; compact/docs/installation.md lignes 21-34; compact/scripts/preflight.sh

  4. Secrets : scripts/gen-secrets.sh crée .env (0600) depuis .env.example avec DJANGO_SECRET_KEY, DB_PASSWORD, REDIS_PASSWORD, RAG_OPS_METRICS_TOKEN, FEEDBACK_PSEUDONYM_SALT et les URL Redis ; refuse d’écraser un .env existant (--force).

    Source : compact/docs/installation.md lignes 36-45; compact/scripts/gen-secrets.sh

  5. (Facultatif) Ajuster .env : COMPACT_FRONTEND_PORT, FRONTEND_APP_ORIGIN / DJANGO_CSRF_TRUSTED_ORIGINS (si reverse-proxy TLS), budgets COMPACT_MEM_*, RAGATM_OPEN_DIR / AI_GATEWAY_OPEN_DIR si la disposition des clones diffère.

    Source : compact/.env.example; compact/docs/configuration.md lignes 11-22, 60-64; installation.md lignes 75-77 — déduit

  6. Construire les images : docker compose build (backend, frontend Next.js, ai-gateway). Images tierces épinglées par digest. Internet requis.

    Source : compact/docs/installation.md lignes 47-55

  7. Approvisionner les modèles (phase explicite, Internet requis) : scripts/provision-models.sh — granite-embedding:278m, qwen2.5:1.5b-instruct, bge-reranker-v2-m3 ; écrit state/provision-manifest.json puis arrête les services d’approvisionnement. Option --with-12gb (profil non qualifié).

    Source : compact/docs/installation.md lignes 57-63; compact/docs/approvisionnement-modeles.md; compact/scripts/provision-models.sh

  8. Démarrer la pile en mode nominal (hors ligne) : scripts/up.sh (docker compose up -d + attente de santé).

    Source : compact/docs/installation.md ligne 68; compact/scripts/up.sh

  9. Créer le premier compte : RAGATM_ADMIN_EMAIL=admin@example.org RAGATM_ADMIN_PASSWORD='' scripts/bootstrap-admin.sh (idempotent ; superutilisateur + workspace « Compact » + espace « Initial RAG »).

    Source : compact/docs/installation.md ligne 69; compact/docs/exploitation.md lignes 15-23; compact/scripts/bootstrap-admin.sh

  10. Ouvrir http://localhost:18080/login ; la première connexion enrôle obligatoirement un second facteur TOTP (application d’authentification) ; aucun compte ne peut s’en passer. Les autres comptes se créent par invitation (aucune inscription publique).

    Source : compact/docs/installation.md lignes 72-73; compact/docs/exploitation.md lignes 21-23; docs/01-overview/decisions/ADR-003

  11. (Recommandé) Vérifier : scripts/diagnose.sh (états, sondes non inférentielles) et scripts/offline-check.sh (aucune sortie Internet, un seul port publié).

    Source : compact/docs/exploitation.md lignes 25-38, 69-77

  12. (Facultatif) Exposition hors boucle locale : placer un reverse-proxy TLS devant 127.0.0.1:18080 et renseigner FRONTEND_APP_ORIGIN et DJANGO_CSRF_TRUSTED_ORIGINS. Aucun TLS dans la pile.

    Source : compact/docs/installation.md lignes 75-77; compact/docs/limites-et-capacites.md ligne 25

  13. (Facultatif, hors qualification Compact) AI Gateway Pool Open : déploiement séparé (deploy/compose/pool/), rejoint le réseau Docker où vit ai-gateway (UPSTREAM_NETWORK, ex. ragatm-compact_ai), publie 127.0.0.1:18090. Le repointage de RAGatm vers le Pool n’est pas documenté dans le kit Compact.

    Source : ai-gateway-pool-open/README.md lignes 21-35; deploy/compose/pool/README.md; deploy/compose/pool/.env.example ligne 12 — déduit

Commandes publiées

Copiées des fichiers de documentation du dépôt ragatm-open, avec leur source.

Cloner les deux dépôts requis

git clone https://github.com/ragatm-open/ragatm-open.git
git clone https://github.com/ragatm-open/ai-gateway-open.git   # requis ; placé à côté de ragatm-open/
cd ragatm-open/compact && scripts/preflight.sh

Source : ragatm-open/README.md, lignes 35-37

Générer les secrets

scripts/gen-secrets.sh          # crée .env (0600) depuis .env.example

Source : ragatm-open/compact/docs/installation.md, lignes 39

Construire les images

docker compose build            # backend, frontend (Next.js), ai-gateway

Source : ragatm-open/compact/docs/installation.md, lignes 50

Approvisionner les modèles

scripts/provision-models.sh     # granite-embedding:278m, qwen2.5:1.5b-instruct, bge-reranker-v2-m3

Source : ragatm-open/compact/docs/installation.md, lignes 62

Démarrer et créer le premier compte

scripts/up.sh
RAGATM_ADMIN_EMAIL=admin@example.org RAGATM_ADMIN_PASSWORD='<mot de passe ≥ 12 caractères>' scripts/bootstrap-admin.sh
# puis ouvrir http://localhost:18080/login

Source : ragatm-open/compact/docs/installation.md, lignes 68-72

Vérifier

scripts/diagnose.sh
scripts/offline-check.sh

Source : ragatm-open/compact/docs/exploitation.md, lignes 25-38, 69-77

« Il n’existe pas d’installation en une commande. » (documentation Compact)

Après l’installation

  • La première connexion enrôle obligatoirement un second facteur TOTP ; aucun compte n’en est dispensé.
  • Les autres comptes se créent par invitation : il n’y a pas d’inscription publique.
  • Pour exposer l’application au-delà de la boucle locale, placez un reverse proxy TLS devant 127.0.0.1:18080 et renseignez FRONTEND_APP_ORIGIN et DJANGO_CSRF_TRUSTED_ORIGINS.
  • Sauvegarde : scripts/backup.sh (base, originaux, configuration) ; restauration documentée vers une instance isolée.
  • Diagnostic : scripts/diagnose.sh et scripts/offline-check.sh (aucune sortie Internet, un seul port publié).
Formulaire de connexion avec champs adresse e-mail et mot de passe, à côté d’une illustration du parcours document → réponse vérifiable.
Page de connexion de RAGatm Open (édition Open, profil Compact).
Écran de vérification du code à usage unique généré par une application d’authentification.
Second facteur TOTP obligatoire après le mot de passe.

Captures réalisées sur une instance RAGatm Open isolée (édition Open, profil Compact sur CPU, reranker désactivé pour la capture), avec les documents fictifs publiés dans le dépôt et un compte de démonstration.

Et le Pool ?

AI Gateway Pool Open est facultatif et absent du profil Compact. Il se déploie séparément et rejoint le réseau Docker de la passerelle. Le repointage de RAGatm Open vers un Pool n’est pas documenté dans le kit Compact.

Guides officiels

La documentation d’installation vit dans les dépôts ; ce site n’en est qu’un résumé.