Installation de Chatbotaurus

Ce guide installe Chatbotaurus en développement local. La pile est écrite en Rust : forge-api (Axum, SeaORM) pour le backend et forge-ui (Dioxus 0.7) pour l'interface. Pour aller plus vite, voir le démarrage rapide.

Ce guide ne couvre pas l'installation sur un serveur : pour la production (réseaux, volumes, unités Quadlet, mise à jour), voir Déploiement avec Podman.

Prérequis

Le chemin de référence du dépôt est Windows (PowerShell) : les lanceurs de développement sont des scripts .ps1. Sous Linux ou macOS, utilisez les commandes cargo et dx ci-dessous.

1. Cloner le dépôt

git clone <url-du-depot>
cd <dossier-du-depot>

2. Compiler le workspace

cargo build --workspace

Le workspace compte 20 crates (forge-core, forge-api, forge-ui, forge-auth, forge-db, forge-mcp, forge-cli, forge-gateway, forge-voice, forge-ops, forge-audit, forge-docs, entre autres). Une première compilation à froid est longue.

3. Configurer l'environnement

cp .env.example .env

Les valeurs secrètes de .env.example sont des gabarits CHANGE_ME_... que l'application refuse au démarrage : remplacez-les. Pour générer un secret : openssl rand -hex 64.

Variables essentielles (chacune est lue par le code, voir crates/forge-core/src/config.rs) :

# Backend
PORT=3000
DATABASE_URL=postgresql://<utilisateur>:<mot-de-passe>@localhost:5432/<base>
REDIS_URL=redis://localhost:6380
JWT_SECRET=<secret-genere>
AT_REST_ENCRYPTION_KEY=<secret-genere>

# Vecteurs et secrets
QDRANT_URL=http://localhost:6334
BAO_ADDR=http://localhost:8200

# Modèles (Ollama)
OLLAMA_BASE_URL=http://localhost:11434

# Courriel (second facteur par code)
SMTP_HOST=<serveur-smtp>
SMTP_PORT=587
SMTP_USER=<compte>
SMTP_PASSWORD=<mot-de-passe-applicatif>
SMTP_FROM=<adresse-expediteur>

# SSO OIDC (Authentik), facultatif
AUTHENTIK_SERVER_URL=http://localhost:9000
AUTHENTIK_CLIENT_ID=<identifiant-client>
AUTHENTIK_CLIENT_SECRET=<secret-client>

# Journalisation
RUST_LOG=info,forge_api=debug

Notes (la liste complète des variables est dans Variables d'environnement) :

• FORCE_2FA vaut vrai par défaut : le démarrage exige alors SMTP_HOST.
• AT_REST_ENCRYPTION_KEY chiffre les identifiants stockés ; sans elle, la clé dérive de JWT_SECRET.
• .env doit être lisible par dotenvy : une valeur contenant un espace doit être entre guillemets, sinon tout le fichier est ignoré.
• Il n'existe pas de variables CSRF_SECRET ni TOTP_ISSUER.

4. Démarrer l'infrastructure

podman-compose -p chatbotaurus-vps1 -f podman-compose.yml up -d

Ce plan (détail dans Déploiement avec Podman) démarre PostgreSQL, Valkey, Qdrant, Ollama, Authentik, OpenBao, les services de voix et l'observabilité. Le second plan, mgaas-vps2 (podman-compose.vps2.yml), porte la passerelle et les serveurs mcp-*. Tout service futur y est ajouté dans ce fichier, jamais lancé à la main.

Vérifiez que les conteneurs tournent avec podman ps (voir Gestion des conteneurs). Si l'un d'eux manque, voir Problèmes connus. Téléchargez aussi les modèles de dialogue avant la première conversation (section « Modèles » plus bas).

5. Initialiser la base

Les migrations s'appliquent aussi au démarrage de forge-api. Pour migrer sans lancer le serveur :

cargo run -p forge-cli -- db migrate

6. Lancer en développement

Backend, port 3000

cargo run -p forge-api

Sous Windows, le lanceur de référence est scripts/dev/run-forge-api.ps1. Il copie le binaire avant de le lancer (la compilation reste possible pendant que le serveur tourne) et exige la variable ADMIN_PASSWORD (12 caractères ou plus) :

$env:ADMIN_PASSWORD = "<mot-de-passe-admin-12-caracteres-ou-plus>"
powershell -File scripts\dev\run-forge-api.ps1

scripts/dev/watch-forge-api.ps1 recompile et remplace le binaire à chaque modification du backend.

Routes principales (contrat complet : Documentation Swagger) :

• GET /api/v1/health et GET /api/v1/healthz : état du service.
• GET /api/v1/readyz : base et Valkey joignables.
• POST /api/v1/predictions et POST /api/v1/predictions/stream : inférence.
• GET /api/v1/mcp/catalogue : catalogue des connecteurs (authentifié).
• POST /api/v1/mcp : transport MCP (authentifié).

Frontend, port 8080

dx serve --platform web --port 8080 --package forge-ui

Sous Windows : pwsh -File scripts\dev\run-dx.ps1. Ce lanceur utilise un répertoire de build séparé (target-dx) pour que cargo build ne bloque pas dx. dx recharge à chaud : ne le relancez pas pour un changement de code. pwsh -File scripts\dev\run-dx.ps1 -Status donne l'état du serveur.

Ouvrez l'interface locale (http://localhost:8080).

Autres plateformes

forge-ui se compile pour les cibles de Dioxus (web, desktop, android, ios, server, liveview), par exemple :

dx serve --platform desktop --package forge-ui

La cible web est la seule suivie en continu.

Ce livre

cargo run -p forge-docs               # construit le livre et le copie dans forge-ui/public/docs
cargo run -p forge-docs -- --clean    # purge book/ et public/docs/ avant de construire

dx serve sert ensuite le livre sous /docs/. L'option --serve (aperçu avec rechargement) n'existe pas : le binaire n'accepte que --src, --dst, --clean, --no-copy et --keep-html-urls.

Modèles

Le dialogue utilise EuroLLM 1.7B, avec ministral-3:3b en repli. Le modèle d'embedding (384 dimensions) est chargé par fastembed dans le processus forge-api : il ne passe pas par Ollama. Détails dans Fournisseurs.

podman exec forge-ollama ollama pull cas/eurollm-1.7b-instruct-q8
podman exec forge-ollama ollama pull ministral-3:3b

Vérification

curl http://localhost:3000/api/v1/health
cargo test -p forge-replay
cargo test -p forge-api

La première commande rend un JSON avec "status":"ok" (le même que dans le démarrage rapide) ; les deux suivantes doivent se terminer sans test en échec.

La CI (voir Contribuer) exécute aussi cargo clippy --workspace -- -D warnings et cargo fmt --check.

Prochaines étapes

• Configurer les fournisseurs de modèles
• Démarrage rapide
• Architecture
• Utiliser les connecteurs MCP

Voir aussi

• Prise en main guidée : créer le compte et tester le chat une fois la pile lancée
• Déploiement avec Podman : passer du développement local aux unités Quadlet
• Problèmes connus : pannes fréquentes au démarrage : Podman, Ollama, OpenBao, Authentik
• Diagnostics et signalement : vérifier chaque service après le démarrage