← Documentation API Reference

Guide de Déploiement AISIA

Version : 4.15.0 Société : AISIA — Structure juridique en cours de création URL publique : https://aisia.fr/

---

Table des matières

1. Architectures de déploiement 2. Docker Compose autonome 3. Docker Swarm cluster 4. Images Docker 5. Variables d'environnement 6. Docker secrets 7. Première installation 8. Mise à jour 9. Configuration Traefik 10. Vérification post-déploiement 11. Rollback 12. Troubleshooting

---

1. Architectures de déploiement

AISIA supporte deux modes de déploiement :

Mode autonome (Docker Compose)

Idéal pour le développement local, les tests, ou un déploiement mono-serveur. Tous les services tournent sur une seule machine.

docker-compose.autonomous.yml
├── aisia-api (FastAPI, port 8000)
├── ollama (runtime local)
├── mariadb
├── redis
├── qdrant
└── prometheus

Mode cluster (Docker Swarm)

Déploiement production distribué sur 21 noeuds. Utilise deux stacks :

stack-poc-global-reuse.yml (aisia)
├── api (FastAPI, 14 replicas)
├── bot (interaction bot, 1 replica)
├── ollama (3 replicas sur RPi)
├── gpu (modèles GPU sur Jetson Xavier AGX)
└── ring (ring-mining-1)


stack-core.yml (aisia-core)
├── mariadb (Galera 3 noeuds NAS)
├── redis (+ replica)
├── qdrant (vector DB)
├── prometheus
└── grafana

---

2. Docker Compose autonome

Prérequis

Docker Engine >= 24.0
Docker Compose >= 2.20
4 Go de RAM minimum (8 Go recommandés)
10 Go d'espace disque

Fichiers de configuration

ai-aisia-lab/
├── deploy/
│   ├── docker-compose.autonomous.yml
│   └── prometheus.autonomous.yml
├── .env.autonomous
└── Dockerfile

Démarrage

cd ai-aisia-lab

Copier et adapter le fichier d'environnement
cp .env.autonomous.example .env.autonomous
Éditer .env.autonomous avec vos clés API
Lancer la stack
docker compose --env-file .env.autonomous \
  -f deploy/docker-compose.autonomous.yml up -d --build

Vérifier le statut
docker compose --env-file .env.autonomous \
  -f deploy/docker-compose.autonomous.yml ps

Arrêt

docker compose --env-file .env.autonomous \
  -f deploy/docker-compose.autonomous.yml down

Arrêt avec suppression des volumes (reset complet)

docker compose --env-file .env.autonomous \
  -f deploy/docker-compose.autonomous.yml down -v

---

3. Docker Swarm cluster

Prérequis

Docker Swarm initialisé sur le manager (freebox-swarm, 192.168.1.1)
Workers joints au Swarm (raspberrypi01 à raspberrypi12, toolsbox, nvidia)
Registry privé accessible (192.168.1.1:5002)
NAS monté sur /mnt/docker/AISIA
Labels Swarm configurés sur les noeuds

Stacks

#### Stack principale : aisia

# Déployer la stack AISIA
docker stack deploy -c deploy/stack-poc-global-reuse.yml aisia

Services :

aisia_api : API FastAPI (14 replicas, ARM64)
aisia_bot : Bot d'interaction (1 replica, AMD64 sur toolsbox)
aisia_ollama : Runtime Ollama (3 replicas sur RPi)
aisia_gpu : Modèles GPU (1 replica sur Jetson Xavier AGX)
aisia_ring : Ring mining (1 replica sur ring-mining-1)

#### Stack core : aisia-core

# Déployer la stack de services fondamentaux
docker stack deploy -c deploy/stack-core.yml aisia-core

Services :

aisia-core_mariadb : Base de données MariaDB
aisia-core_redis : Cache Redis + replica
aisia-core_qdrant : Base vectorielle Qdrant
aisia-core_prometheus : Monitoring Prometheus
aisia-core_grafana : Dashboards Grafana

Labels Swarm requis

Les services utilisent des contraintes de placement basées sur les labels Docker :

# Sur le manager (192.168.1.1)
docker node update --label-add aisia.role=manager freebox-swarm

Sur les workers RPi
docker node update --label-add aisia.role=worker raspberrypi01
docker node update --label-add aisia.ollama=true raspberrypi01
Répéter pour raspberrypi02, raspberrypi03
Sur toolsbox (192.168.1.240)
docker node update --label-add aisia.role=toolsbox toolsbox

Sur Jetson Xavier AGX (192.168.1.200)
docker node update --label-add aisia.gpu=true nvidia
docker node update --label-add aisia.role=gpu nvidia

Sur NAS nodes (pour MariaDB Galera)
docker node update --label-add aisia.nas=true <node_name>

---

4. Images Docker

Images officielles

Image	Architecture	Usage
`192.168.1.1:5002/aisia:v4.15.0`	ARM64	API FastAPI sur RPi
`aisia:v4.15.0-amd64`	AMD64	Bot sur toolsbox

Construction des images

Les builds doivent être effectués sur toolsbox (192.168.1.240) qui dispose de 8 vCPU et 12 Go de RAM, avec support cross-platform.

# Connexion à toolsbox
ssh slambert@lambda.freeboxos.fr  # puis jump vers toolsbox
Ou en LAN direct :
ssh slambert@192.168.1.240

Build ARM64 (pour les RPi)
cd /mnt/docker/AISIA/ai-aisia-lab
docker buildx build \
  --platform linux/arm64 \
  -t 192.168.1.1:5002/aisia:v4.15.0 \
  -f Dockerfile \
  --push .

Build AMD64 (pour le bot sur toolsbox)
docker build \
  -t aisia:v4.15.0-amd64 \
  -f Dockerfile .

Dockerfile

Le Dockerfile utilise une image de base Python 3.11 slim et installe les dépendances depuis requirements.txt. L'application démarre avec Uvicorn sur le port 8000.

---

5. Variables d'environnement

Variables essentielles

Variable	Défaut	Description
`APP_ENV`	development	Environnement (development/staging/production)
`APP_VERSION`	4.15.0	Version de l'application
`APP_LOG_LEVEL`	INFO	Niveau de log (DEBUG/INFO/WARNING/ERROR)
`APP_INTERNAL_TOKEN`	""	Token interne pour communication inter-services

Base de données

Variable	Défaut	Description
`DATABASE_URL`	-	URL complète (prioritaire)
`DATABASE_HOST`	localhost	Hôte MariaDB
`DATABASE_PORT`	3306	Port MariaDB
`DATABASE_NAME`	ai_router	Nom de la base
`DATABASE_USER`	ai_router	Utilisateur DB
`DATABASE_PASSWORD`	""	Mot de passe (ou Docker secret)

Alias supportés : MYSQL_HOST, MARIADB_HOST, MYSQL_DATABASE, etc.

Redis

Variable	Défaut	Description
`REDIS_URL`	redis://localhost:6379/0	URL de connexion Redis
`CACHE_TTL_SECONDS`	3600	Durée de vie du cache (1h)

Qdrant

Variable	Défaut	Description
`QDRANT_URL`	-	URL complète Qdrant
`QDRANT_HOST`	localhost	Hôte Qdrant
`QDRANT_PORT`	6333	Port Qdrant
`QDRANT_KNOWLEDGE_COLLECTION`	mtp_knowledge	Collection knowledge base
`QDRANT_TRAINING_COLLECTION`	mtp_training_pairs	Collection paires entraînement

Autonomie local-first

Variable	Défaut	Description
`AUTONOMOUS_LOCAL_ENABLED`	false	Activer le mode local-first
`AUTONOMOUS_LOCAL_HOST`	http://localhost:11434	URL du serveur Ollama
`AUTONOMOUS_PRIMARY_MODEL`	llama3.2:3b	Modèle principal
`AUTONOMOUS_FALLBACK_MODEL`	llama3.2:1b	Modèle de secours
`AUTONOMOUS_LOCAL_TIMEOUT_S`	15	Timeout par requête locale
`AUTONOMOUS_CONFIDENCE_THRESHOLD`	0.75	Seuil de confiance
`AUTONOMOUS_MAX_TOKENS`	1024	Tokens max par réponse locale
`AUTONOMOUS_SELF_CONSISTENCY_SAMPLES`	3	Échantillons pour self-consistency

Routage

Variable	Défaut	Description
`BANDIT_STRATEGY`	ucb1	Stratégie bandit (ucb1/thompson)
`BANDIT_EXPLORATION_BONUS`	1.4142 (sqrt 2)	Bonus d'exploration UCB1
`CB_FAILURE_THRESHOLD`	5	Échecs avant circuit ouvert
`CB_TIMEOUT_S`	60	Durée circuit ouvert
`CB_HALF_OPEN_MAX_CALLS`	3	Appels test half-open

Authentification

Variable	Défaut	Description
`AUTH_ENABLED`	true	Activer l'authentification
`AUTH_SECRET_KEY`	change-me-in-production	Clé secrète JWT
`AUTH_TOKEN_EXPIRE_HOURS`	72	Durée de validité du token JWT
`AUTH_FRONTEND_BASE_URL`	""	URL de base du frontend
`AUTH_GOOGLE_CLIENT_ID`	""	Client ID Google OIDC
`AUTH_GOOGLE_CLIENT_SECRET`	""	Client Secret Google OIDC
`AUTH_MICROSOFT_CLIENT_ID`	""	Client ID Microsoft
`AUTH_MICROSOFT_TENANT_ID`	common	Tenant Microsoft
`AUTH_FRANCECONNECT_CLIENT_ID`	""	Client ID FranceConnect+
`AUTH_OKTA_CLIENT_ID`	""	Client ID Okta
`AUTH_OKTA_DOMAIN`	""	Domaine Okta

Maintenance

Variable	Défaut	Description
`MAINTENANCE_SCHEDULER_ENABLED`	false	Activer le scheduler
`MAINTENANCE_SCHEDULER_POLL_INTERVAL_S`	30	Intervalle de poll
`MAINTENANCE_SCHEDULER_MAX_CONCURRENT_TASKS`	2	Tâches simultanées max
`MAINTENANCE_COMMAND_TIMEOUT_S`	900	Timeout commande (15min)
`MAINTENANCE_CATALOG_PATH`	./maintenance_tasks.yaml	Chemin du catalogue

Bot

Variable	Défaut	Description
`BOT_ENABLED`	true	Activer le bot
`BOT_CYCLE_INTERVAL_S`	120	Intervalle entre cycles (2min)
`BOT_PROVIDERS_PER_CYCLE`	5	Providers testés par cycle
`BOT_PROMPTS_PER_CYCLE`	3	Prompts par cycle
`BOT_MAX_CONCURRENT_QUERIES`	8	Requêtes parallèles max
`BOT_LOCAL_ONLY`	true	Tester uniquement les modèles locaux

RGPD

Variable	Défaut	Description
`RGPD_USER_RETENTION_DAYS`	1095	Rétention comptes (3 ans)
`RGPD_AUDIT_RETENTION_DAYS`	365	Rétention logs audit (1 an)
`RGPD_DPO_EMAIL`	contact@aisia.fr	Email du DPO

---

6. Docker secrets

En production Swarm, les informations sensibles sont gérées via Docker secrets plutôt que des variables d'environnement.

Secrets requis

AISIA lit automatiquement les fichiers dans /run/secrets/ au démarrage :

Secret	Variable remplacée	Description
`database_password`	DATABASE_PASSWORD	Mot de passe MariaDB
`mysql_password`	DATABASE_PASSWORD	Alias MariaDB
`auth_secret_key`	AUTH_SECRET_KEY	Clé secrète JWT
`app_secret_key`	AUTH_SECRET_KEY	Alias clé JWT
`auth_google_client_secret`	AUTH_GOOGLE_CLIENT_SECRET	Secret Google OIDC

Secrets pour les clés API des providers

Chaque provider peut avoir sa clé API définie comme un Docker secret. Le nom du secret correspond à la variable d'environnement en minuscules :

# Exemples de création de secrets
echo "sk-xxx..." | docker secret create openai_api_key -
echo "sk-ant-xxx..." | docker secret create anthropic_api_key -
echo "xxx..." | docker secret create groq_api_key -
echo "xxx..." | docker secret create cerebras_api_key -
echo "xxx..." | docker secret create deepseek_api_key -
echo "xxx..." | docker secret create mistral_api_key -
echo "xxx..." | docker secret create cohere_api_key -
echo "xxx..." | docker secret create gemini_api_key -
echo "xxx..." | docker secret create together_api_key -
echo "xxx..." | docker secret create fireworks_api_key -
echo "xxx..." | docker secret create perplexity_api_key -
echo "xxx..." | docker secret create replicate_api_key -
echo "xxx..." | docker secret create huggingface_api_key -

Création en masse

# Script fourni dans le dépôt
bash deploy/setup-secrets.sh

Résolution des clés

AISIA résout les clés API dans cet ordre de priorité : 1. Cache DB admin (interface d'administration) 2. Variable d'environnement 3. Docker secret (/run/secrets/)

---

7. Première installation

Étape 1 : Préparer le Swarm

# Sur le manager
docker swarm init --advertise-addr 192.168.1.1

Sur chaque worker
docker swarm join --token SWMTKN-xxx 192.168.1.1:2377

Étape 2 : Configurer les labels

# Appliquer les labels de placement (voir section 3)
docker node update --label-add aisia.role=worker raspberrypi01
...

Étape 3 : Créer les secrets

bash deploy/setup-secrets.sh

Étape 4 : Déployer la stack core

docker stack deploy -c deploy/stack-core.yml aisia-core
Attendre que MariaDB, Redis et Qdrant soient prêts (~30s)
docker service ls

Étape 5 : Déployer la stack AISIA

docker stack deploy -c deploy/stack-poc-global-reuse.yml aisia
Vérifier que les 14 replicas de l'API démarrent
docker service ls | grep aisia

Étape 6 : Obtenir un token admin

curl -X POST https://aisia.fr/auth/bootstrap-admin \
  -H "Content-Type: application/json" \
  -d '{"app_secret_key": "VOTRE_CLE"}'

Étape 7 : Vérifier le déploiement

# Health check
curl https://aisia.fr/health

Self-audit
curl -H "Authorization: Bearer TOKEN" \
  https://aisia.fr/admin/self-audit

---

8. Mise à jour

Procédure de mise à jour (zero downtime)

# 1. Build la nouvelle image sur toolsbox
ssh slambert@192.168.1.240
cd /mnt/docker/AISIA/ai-aisia-lab
docker buildx build --platform linux/arm64 \
  -t 192.168.1.1:5002/aisia:v4.15.0 --push .

2. Mettre à jour la stack (rolling update)
docker stack deploy -c deploy/stack-poc-global-reuse.yml aisia

3. Vérifier le déploiement
docker service ls | grep aisia
curl https://aisia.fr/health

Docker Swarm effectue un rolling update automatique : les nouvelles replicas démarrent avant que les anciennes ne soient arrêtées.

---

9. Configuration Traefik

AISIA utilise Traefik comme reverse proxy en mode file provider.

Régénérer la configuration Traefik

Après chaque déploiement de aisia_api, les adresses IP des containers peuvent changer. Il faut régénérer services.yml :

bash deploy/update-traefik-backend.sh

Configuration DNS

Le point d'accès unique est https://aisia.fr/. Les anciennes routes lambda.freeboxos.fr ont été supprimées.

---

10. Vérification post-déploiement

Checks manuels

# 1. Health check
curl https://aisia.fr/health
Attendu : {"status": "ok", "database": {"status": "ok"}, ...}
2. Providers disponibles
curl https://aisia.fr/v1/providers | python3 -m json.tool | head -5
Attendu : liste de 52+ providers
3. Chat fonctionnel
curl -X POST https://aisia.fr/v1/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"prompt": "Bonjour"}}'
Attendu : réponse avec texte et latence
4. Self-audit (avec token admin)
curl -H "Authorization: Bearer TOKEN" \
  https://aisia.fr/admin/self-audit

Check automatisé

# Smoke test golden path
python3 deploy/smoke-golden-path.py

Smoke test local-first
python3 deploy/smoke-local-first.py

Smoke test providers
python3 deploy/smoke-providers.py

Validation conformité complète
bash deploy/validate-full-compliance.sh

---

11. Rollback

Rollback rapide (image précédente)

# Mettre à jour le tag dans le fichier stack
Puis redéployer
docker stack deploy -c deploy/stack-poc-global-reuse.yml aisia

Rollback base de données

Les tables MariaDB utilisent le préfixe aisia_. Les migrations sont idempotentes (CREATE TABLE IF NOT EXISTS). Un rollback de code ne nécessite généralement pas de rollback de schéma.

---

12. Troubleshooting

Le service API ne démarre pas

# Consulter les logs
docker service logs aisia_api --tail 100

Vérifier les contraintes de placement
docker service ps aisia_api --no-trunc

MariaDB inaccessible

# Vérifier que le service tourne
docker service ls | grep mariadb

Tester la connectivité
docker exec $(docker ps -q -f name=mariadb) \
  mysql -u aisia -p aisia -e "SELECT 1"

Redis inaccessible

AISIA fonctionne en mode dégradé sans Redis :

Le bandit router utilise un état en mémoire locale
Les circuit breakers ne sont pas partagés entre replicas
Les conversations ne sont pas cachées

Qdrant inaccessible

Sans Qdrant :

Le RAG est désactivé (pas de contexte enrichi)
La knowledge base n'est pas disponible
La boucle d'apprentissage ne stocke pas les paires

Jitter de démarrage

AISIA ajoute un jitter aléatoire de 0-15 secondes au démarrage pour éviter que les 14 replicas ne tentent de se connecter simultanément à MariaDB. C'est un comportement normal.

---

Document AISIA v4.21.0