15. Déploiement & Infra
ECHO est conçu pour transformer une machine standard en un serveur d'intelligence souveraine. Le scénario nominal consiste à utiliser un poste Windows 11 Pro comme hôte matériel, exécutant une Machine Virtuelle Ubuntu 24.04 isolée via Hyper-V. La totalité de la pile Docker ECHO s'exécute dans cette VM, garantissant une étanchéité totale entre les outils quotidiens de l'utilisateur et son infrastructure IA personnelle.
💡 Trois voies d'installation
ECHO supporte trois méthodes de déploiement selon le contexte : Hyper-V (production souveraine, isolation maximale), Linux natif (serveur dédié) et WSL2 (développement ou test unitaire sur Windows). Toutes convergent vers la même pile Docker et le même état final.
Voie A - Hyper-V (Production Souveraine)
Le scénario Hyper-V est le plus abouti. Il utilise le script PowerShell
install-hyperv.ps1 exécuté depuis le poste Windows, lequel
orchestre la création et le provisioning automatique d'une VM Ubuntu fraîche
via le mécanisme cloud-init.
Phase 1 - Assemblage et injection (hôte Windows)
Le script d'installation rassemble les sources locales et provisionne de manière transparente la machine virtuelle. Il prépare les fondations en allouant les ressources matérielles nécessaires au bon fonctionnement de l'intelligence artificielle, sans exiger de paramétrage complexe.
Phase 2 - Provisioning automatisé (VM Linux)
Au premier démarrage, le système s'installe de lui-même de manière silencieuse. Il déploie l'ensemble des prérequis logiciels nécessaires au fonctionnement du serveur de manière autonome, assurant un système opérationnel et sécurisé.
Phase 3 - Synchronisation des sources
L'outil de synchronisation distribue les fichiers sources vers leur emplacement définitif au sein de la machine virtuelle Linux.
Phase 4 - Orchestration Docker
L'orchestrateur de déploiement assure le démarrage séquentiel de toute la pile applicative ECHO, configurant au passage les variables d'environnement globales et connectant Open WebUI au moteur d'IA.
Voie B - Linux Natif (Serveur Dédié)
curl -fsSL https://raw.githubusercontent.com/Wilfried-Barnavon-Perso/echo-framework/main/install-linux.sh | sudo bash
# Ou sur une branche spécifique :
sudo bash <(curl -fsSL https://raw.githubusercontent.com/Wilfried-Barnavon-Perso/echo-framework/main/install-linux.sh) --branch dev
install-linux.sh est idempotent : si ECHO est déjà installé,
une seconde exécution effectue une mise à jour propre. Il installe Docker, Docker Compose v2,
jq, yq, git, chrony, puis clone le
dépôt dans /opt/ECHO/source et enchaîne sync-echo.sh et
install-stack.sh.
Voie C - WSL2 (Développement)
curl -fsSL https://raw.githubusercontent.com/Wilfried-Barnavon-Perso/echo-framework/main/install-wsl2.sh | sudo bash
Spécificités gérées par install-wsl2.sh :
-
Détection systemd : si
/etc/wsl.confdéclaresystemd=true, Docker est activé comme service permanent. Sinon, fallback surservice docker start. -
Accès double : l'interface est accessible depuis WSL2
(
http://<IP-WSL>:3000) et depuis l'hôte Windows (http://localhost:3000) grâce au port forwarding automatique de WSL2. -
chronyn'est pas installé : la synchronisation de l'heure est assurée par l'hôte Windows.
Activer systemd dans WSL2
Ajouter dans /etc/wsl.conf :
[boot]
systemd=true
Puis exécuter wsl --shutdown depuis PowerShell et relancer la distribution.
Docker démarrera alors automatiquement à chaque ouverture de WSL2.
Comparatif des trois méthodes
| Critère | Hyper-V | Linux Natif | WSL2 |
|---|---|---|---|
| Isolation | Maximale (VM dédiée) | OS dédié | Partielle (noyau partagé) |
| Prérequis | Windows 11 Pro + Hyper-V + 8 Go RAM | Ubuntu 22.04+ / Debian 12+ | WSL2 activé sur Windows 10/11 |
| Complexité de démarrage | Élevée (VM + cloud-init) | Faible | Faible |
| Idempotent | Non (VM recréée) | Oui | Oui |
| Accès depuis Windows | Via IP statique de la VM | Non direct | localhost natif |
| Usage recommandé | Production souveraine | Serveur dédié | Développement / test unitaire |
Cycle de vie et maintenance
Une fois déployée, l'infrastructure ECHO se gère via des commandes globales disponibles partout dans le shell Linux :
| Commande | Action | Impact |
|---|---|---|
update-echo |
Mise à jour du code Python uniquement. | Redémarrage « hot reload » des micro-services. Données préservées. |
upgrade-echo |
Mise à niveau majeure de l'infrastructure. | Re-synchronisation complète + rebuild des images Docker locales. |
rebuild-echo |
Réinitialisation intégrale (destructrice). | Suppression de tous les conteneurs, volumes, images et secrets. Remise à zéro totale - données perdues. |
clean-echo |
Maintenance et purge de sécurité Docker. | Nettoyage des images orphelines, du cache de build et des logs sans perte de données. |
logs-echo / ps-echo |
Diagnostic et supervision en ligne de commande. | Suivi en temps réel des journaux et de l'état des conteneurs de la pile. |
show-echo-admin |
Affiche les identifiants administrateur. | Lecture seule depuis /opt/ECHO/.secrets. |
Quickstart depuis sources locales
# Depuis la racine du dépôt git ECHO cloné localement :
sudo bash 00-echo-scripts/sync-echo.sh --local-only
sudo bash 00-echo-scripts/install-stack.sh
# Interface disponible sur http://localhost:3000⚙️ Dossier d'Ingénierie & Spécifications
1. Configuration Hyper-V & Provisioning (install-hyperv.ps1 v5.210.0)
Lors du déploiement Windows, install-hyperv.ps1 crée une archive ZIP pointant par défaut sur la branche dev du projet (hors .git, .venv, node_modules), génère un disque CIDATA de 64 Mo contenant user-data, meta-data, vendor-data et source.zip, puis provisionne une VM Hyper-V Génération 2 sous Ubuntu 24.04 (4 vCPUs, 8 Go de RAM au démarrage avec allocation dynamique 4 Go – 10 Go, et VHDX dynamique de 100 Go). Au premier démarrage, Subiquity exécute cloud-init, installe Docker Compose v2, jq, yq, git et lance sync-echo.sh puis install-stack.sh.
2. Cartographie Déclarative des Sources (sync-echo.sh v4.11)
| Source (dépôt git) | Destination sur la VM | Contenu |
|---|---|---|
00-echo-scripts/ | /opt/ECHO/echo-scripts/ | Scripts Bash d'administration et liens /usr/local/bin/ |
01-config/ | /opt/ECHO/config/ | Manifestes Compose, Kernel statique, webui-settings.json, webui-banners.json, logging.json |
_assets/images/ | /opt/ECHO/echo-images/ | Ressources graphiques et avatars des modèles ECHO |
docker-python-base/ | /opt/ECHO/docker-python-base/ | Image mutualisée echo-python-base:latest |
10-owui-pipes/ | /opt/ECHO/owui-pipes/ | Orchestrateur Cognitif Python (echo_orchestrator.py, Cortex) |
11-owui-filters/ | /opt/ECHO/owui-filters/ | Filtres Inlet & Outlet |
12-owui-tools/ | /opt/ECHO/owui-tools/ | Outils de l'Arsenal |
13-owui-actions/ | /opt/ECHO/owui-actions/ | Actions interactives HUD |
14-owui-libs/ | /opt/ECHO/owui-libs/ et /app/backend/echo_libs/ | Librairies centrales partagées |
20-docker-admin-manager/ | /opt/ECHO/docker-admin-manager/ | Console Admin Manager (Port 3001) |
21-docker-coding-worker/ | /opt/ECHO/docker-coding-worker/ | Sandbox Code Python 3.14 / Node 22 (Port 5000) |
22-docker-browser-worker/ | /opt/ECHO/docker-browser-worker/ | Browser Worker Playwright (Port 5002) |
23-docker-mcp-broker/ | /opt/ECHO/docker-mcp-broker/ | MCP Broker Proxy HTTP (Port 8000) |
24-docker-echo-auth-manager/ | /opt/ECHO/docker-echo-auth-manager/ | ECHO Auth Manager IdP SSO & MFA (Port 8000) |
25-docker-download-broker/ | /opt/ECHO/docker-download-broker/ | Download Broker Daemon |
26-docker-n8n-worker/ | /opt/ECHO/docker-n8n-worker/ | Headless N8N Worker (Port 5003) |
30-docker-embedding-worker/ | /opt/ECHO/docker-embedding-worker/ | Embedding Worker Harrier-OSS (Port 7997) |
Le script applique un nettoyage conditionnel sed des caractères CRLF/BOM uniquement sur les fichiers impactés afin de préserver les horodatages (mtime) et le cache Docker BuildKit.
3. Séquençage Docker & Autosafety (stack-echo.yml v9.83 & install-stack.sh v6.33)
- Tier 1 (Fondations) : Qdrant (
v1.19.1, IP.103), SearXNG (.101), Watchtower (.102). - Tier 2 (Workers) : Embedding (
.30), Coding Worker (.21surecho-sandbox), Browser Worker (.22), MCP Broker (.23, volume persistantecho-mcp-cache), Download Broker (.25), N8N Worker (.26). - Tier 3 (Cortex) : Open WebUI (
main-slim, IP.100,ENABLE_CONTEXT_COMPACTION=falseneutralisant la compaction native d'Open WebUI au profit du moteur ECHO, labelbunkerweb.MAX_CLIENT_SIZE=4096m, cache persistantPIP_CACHE_DIR=/app/backend/data/.cache/pip,mgzip,dulwich,markitdown[all],h2,pybase64,edge-tts). - Tier 4 (Gouvernance) : Admin Manager (
.20, montages Hot-Reload en lecture seule:rodeserver.py,core/,services/,routes/,templates/et accès aux 5 volumes de données dontecho-n8n-dataetecho-mcp-cache) et ECHO Auth Manager (.24).
install-stack.sh configure l'Autosafety Docker (logs max 10 Mo, cron quotidien /etc/cron.daily/clean-echo), compile l'image socle echo-python-base:latest avec CMAKE_BUILD_PARALLEL_LEVEL=2 et un throttle de 30 jours (.last_base_pull), puis exécute config-owui.sh (v7.69) qui synchronise webui-settings.json et webui-banners.json, purge les modèles fantômes obsolètes en base SQLite et enregistre l'Orchestrateur Cognitif echo_orchestrator ainsi que les filtres, outils et actions HUD. Les conteneurs labellisés echo.hot-reload=true sont rechargés à chaud par update-echo, tandis que rebuild-echo (upgrade-echo.sh v2.8) exige une double saisie de sécurité (CONFIRMER puis DETRUIRE).