docs: add runbook for Hermes Hub deployment (common/hermes-hub-deploiement.md)

common/hermes-hub-deploiement.md

@@ -0,0 +1,70 @@
+# Hermes Hub — Déploiement et Exploitation Multi-Univers sur VPS
+
+**Instance auteur** : gemini / nabil  
+**Date** : 2026-08-19  
+**Tags** : hermes, hub, multi-univers, vps, tailscale, cloudflare-access, fastapi  
+**Statut** : valide
+
+---
+
+## Problème
+
+Nabil dispose de 4 instances Hermes strictement cloisonnées :
+- **TT** (, port 3010, NAS Synology) — Achats Zone Sud, Tunisie Telecom
+- **Nyora** (, port 3020, NAS Synology) — Venture perso, Dr Nexum
+- **Perso** (, port 3031, NAS Synology) — Famille, personnel, santé
+- **Nabil** (, local loopback, VPS Contabo) — Master agent & DSH
+
+L'objectif est d'offrir une interface web unifiée sur le VPS Contabo avec un sélecteur d'univers (workspace switcher), tout en garantissant :
+1. L'absence totale de fuite de contexte ou de mémoire JS entre univers.
+2. La sécurisation des flux distants VPS ↔ NAS sans aucune ouverture de port sur le WAN.
+3. Un découplage complet de la personnalisation (fichiers YAML de persona) et des styles visuels (Design Tokens CSS).
+
+---
+
+## Contexte et contraintes
+
+- **Réseau** : Communication exclusive via le maillage **Tailscale** ( NAS ↔  VPS).
+- **Port Hermes Perso** : Port **3031** fixé définitivement (port 3030 orphelin sur l'hôte NAS).
+- **Sécurité** : Authentification **Cloudflare Access** en amont du Cloudflare Tunnel sur le VPS.
+- **UID/GID** : Conteneurs exécutés sous .
+- **Frontend** : Dark Mode par défaut, palette et typographie basées sur des CSS custom properties () facilement substituables par Claude Design.
+
+---
+
+## Ce qui NE fonctionne PAS
+
+| Tentative | Erreur obtenue / Risque | Raison de l'échec / Solution adoptée |
+|-----------|-------------------------|--------------------------------------|
+| Tunnel WireGuard wg-easy | 0 B reçus, timeout | wg-easy décommissionné le 08/07/2026. Remplacé nativement par Tailscale (44 ms). |
+| Port 3030 pour hermes-perso | Port déjà alloué / conflit | Processus docker-proxy orphelin sur l'hôte NAS sans PID visible. Résolu en fixant définitivement le port 3031. |
+| Déploiement Authelia complet | Complexité & surcoût RAM | Nécessitait d'ajouter Traefik/Nginx sur le VPS uniquement pour le forward-auth. Cloudflare Access retenu. |
+| Ingestion dsh en univers séparé | Perte de contexte | dsh n'est pas un profil conversationnel mais un outil d'exécution locale appelé par l'univers Nabil. |
+
+---
+
+## Solution validée
+
+### 1. Dépôt & Code source
+- Dépôt Gitea : 
+- Architecture : FastAPI + Async Proxy Streaming () + Dynamic Tokens Engine.
+
+### 2. Déploiement sur VPS Contabo ()
+
+
+### 3. Routage Cloudflare Tunnel & Access
+- Ingress Cloudflare Tunnel : 
+- Application Cloudflare Access configurée avec politique OTP / Email autorisée.
+
+---
+
+## Vérification
+
+
+
+---
+
+## Pièges spécifiques
+
+- **DNS Docker sur VPS Contabo** : Toujours inclure  dans le compose car le  local n'est pas résolu depuis les ponts Docker.
+- **Purge mémoire front-end** : La fonction  dans  force systématiquement le déchargement de l'iframe () avant de monter le nouvel univers pour interdire toute fuite d'état JS.