2. Déploiement & Infrastructure
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 rapide 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
deploy-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)
deploy-hyperv.ps1 agit comme assembleur. Il crée une archive ZIP du projet
(hors .git, .venv, node_modules), génère un
disque dur virtuel CIDATA de 100 Mo contenant les fichiers user-data et
meta-data cloud-init, puis crée la VM Hyper-V de Génération 2 avec Secure
Boot désactivé et le disque Seed attaché.
Phase 2 — Provisioning automatisé (VM Linux)
Au premier démarrage, l'installateur Ubuntu (Subiquity) détecte le disque CIDATA et
exécute les instructions cloud-init : installation de Docker, Docker Compose v2,
jq, yq, git et unzip.
L'archive ZIP est extraite dans /opt/ECHO/source, puis
sync-echo.sh --local-only est lancé immédiatement pour distribuer les fichiers.
Phase 3 — Synchronisation des sources (sync-echo.sh)
Ce script est le distributeur du framework. Il copie les fichiers sources
vers leur destination définitive dans /opt/ECHO/ selon la cartographie suivante :
| Source (dépôt git) | Destination sur la VM | Contenu |
|---|---|---|
00-echo-scripts/ | /opt/ECHO/echo-scripts/ | Scripts Bash de contrôle |
01-config/ | /opt/ECHO/config/ | YAML, JSON de configuration |
10-owui-pipes/ | /opt/ECHO/owui-pipes/ | Pipe Engine Python |
11-owui-filters/ | /opt/ECHO/owui-filters/ | Filtres Python |
12-owui-tools/ | /opt/ECHO/owui-tools/ | Outils de l'Arsenal |
13-owui-actions/ | /opt/ECHO/owui-actions/ | Actions HUD |
14-owui-libs/ | /opt/ECHO/owui-libs/ et /app/backend/echo_libs/ | Librairies partagées |
20-docker-admin-manager/ | /opt/ECHO/docker-admin-manager/ | Admin Manager |
21-docker-python-worker/ | /opt/ECHO/docker-python-worker/ | Sandbox Python |
22-docker-browser-agent/ | /opt/ECHO/docker-browser-agent/ | Browser Agent Playwright |
23-docker-embedding-worker/ | /opt/ECHO/docker-embedding-worker/ | Inférence bge-m3 locale |
30-docker-stt-worker/ | /opt/ECHO/docker-stt-worker/ | Worker STT (Faster-Whisper) |
31-docker-tts-worker/ | /opt/ECHO/docker-tts-worker/ | Worker TTS (Kokoro ONNX) |
Le script effectue également une normalisation des fins de lignes (CRLF → LF) et supprime
les BOM UTF-8, puis crée des liens symboliques dans /usr/local/bin/ pour
que toutes les commandes ECHO soient accessibles globalement
(ex. update-echo au lieu de /opt/ECHO/echo-scripts/update-echo.sh).
Phase 4 — Orchestration Docker (install-stack.sh)
Ce script orchestre le démarrage de la pile Docker Compose. Il centralise les secrets
et variables dans /opt/ECHO/.env, calcule dynamiquement les origines CORS
autorisées (ECHO_DETECTED_ORIGINS), puis lève les services.
Une fois les conteneurs actifs, config-owui.sh injecte automatiquement
l'Arsenal (Pipes, Filtres, Outils, Actions) dans l'API d'Open WebUI et configure le
system prompt.
⚠ Dépendances Python additionnelles (stack-echo.yml v9.2)
Le service open-webui installe des packages Python au démarrage
via la commande /bin/bash -c "pip install mgzip dulwich && ./start.sh".
mgzip est requis pour les exports gzip, dulwich (ajouté en v9.2)
est la bibliothèque Git Python pur requise par l'ECHO Codex pour créer et gérer
les dépôts Git sans binaire git installé dans le conteneur.
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 activé | 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 rapide |
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. | Re-synchronisation complète + rebuild des images Docker locales. |
rebuild-echo |
Option nucléaire. | Suppression de tous les conteneurs, volumes, images et secrets. Remise à zéro totale — données perdues. |
show-echo-admin |
Affiche les identifiants administrateur. | Lecture seule depuis /opt/ECHO/.secrets. |
Bouclier BunkerWeb (WAF)
L'activation de BunkerWeb (enable-bunkerweb) transforme l'infrastructure
en plateforme sécurisée exposable sur Internet. BunkerWeb agit comme reverse proxy WAF
(Web Application Firewall) devant Open WebUI et l'Admin Manager, filtrant les requêtes
malveillantes avant qu'elles n'atteignent l'application.
La configuration persistante est stockée dans /opt/ECHO/bunkerweb/.
⚠️ Exposition réseau
Sans BunkerWeb, ECHO n'écoute que sur le réseau Docker interne ou l'interface locale. N'exposer jamais les ports 3000 (Open WebUI) ou 8080 (Admin Manager) directement sur le WAN sans pare-feu applicatif.
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