Module 12 / 18← Ordre des modules
● Interface Web · Docker · accès privé

Open WebUI

Installer Open WebUI dans Docker, conserver ses données de manière persistante et le connecter à l’API OpenAI-compatible de Hermes Agent. Le Golden Build expose l’interface uniquement sur le réseau privé et utilise le VPN pour l’accès distant.

Conteneur

open-webui

Port Web Golden

3000

Données persistantes

/app/backend/data

Lecture seuleModificationValidationOptionnel
Principe Golden : Open WebUI n’est pas publié directement sur Internet. Il est lié à l’adresse LAN choisie pour Jarvis, et tout accès distant doit passer par un VPN ou un autre réseau privé sécurisé.
Persistance : le volume Docker open-webui contient notamment la base webui.db, les uploads et le vector store. Ne supprimez jamais ce volume pour simplement mettre à jour le conteneur.
Secrets : aucune valeur réelle n’est écrite dans cette documentation. Remplacez uniquement les placeholders dans votre environnement local. Le fichier de secret créé ci-dessous doit rester en permissions 600.

Valeurs à préparer

Adresse LAN de JarvisMETTRE_VOTRE_IP_LAN_JARVIS
Clé API HermesMETTRE_VOTRE_CLE_API_HERMES
Port Open WebUI3000
Port API Hermes8642

Installation pas à pas

Docker doit déjà être installé et validé via le Module 02. L’API Hermes doit être opérationnelle via le Module 06.

12.1 · Vérifier Docker

Validation
docker --version
docker compose version
docker info >/dev/null && echo "Docker OK"
Pourquoi : Open WebUI sera exécuté en conteneur Docker.
Résultat attendu : Docker et le plugin Compose répondent sans erreur.

12.2 · Vérifier l’API Hermes avant de continuer

Validation
curl -fsS http://METTRE_VOTRE_IP_LAN_JARVIS:8642/health
Pourquoi : Open WebUI dépendra de cette API pour exposer Hermes comme modèle conversationnel.
Résultat attendu : Le endpoint de santé Hermes répond correctement. Si ce test échoue, revenez au Module 06.

12.3 · Vérifier que le port Web choisi est libre

Lecture seule
ss -lnt | grep ':3000 ' || echo "Port 3000 disponible"
Pourquoi : Éviter un conflit avec un service déjà présent.
Résultat attendu : Aucun listener inattendu sur le port 3000.

12.4 · Préparer le répertoire de configuration privé

Modification
install -d -m 700 ~/.config/jarvis
Pourquoi : Conserver les éléments sensibles nécessaires à l’installation hors des pages HTML et hors de Git.
Résultat attendu : Le répertoire existe avec des permissions restrictives.

12.5 · Générer un secret persistant Open WebUI

Modification
umask 077
printf 'WEBUI_SECRET_KEY=%s\n' "$(openssl rand -hex 32)" > ~/.config/jarvis/open-webui.env
chmod 600 ~/.config/jarvis/open-webui.env
Pourquoi : Open WebUI utilise cette clé pour signer les sessions et protéger certaines données sensibles. Une clé stable évite de casser les sessions lors de la recréation du conteneur.
Résultat attendu : Le fichier existe, contient une clé générée aléatoirement et n’est lisible que par son propriétaire.

12.6 · Vérifier le secret sans l’afficher

Validation
stat -c '%a %n' ~/.config/jarvis/open-webui.env
grep '^WEBUI_SECRET_KEY=' ~/.config/jarvis/open-webui.env | sed 's/=.*/=<SECRET_PRESENT>/'
Pourquoi : Contrôler la présence de la clé sans divulguer sa valeur.
Résultat attendu : Permissions 600 et affichage uniquement de <SECRET_PRESENT>.

12.7 · Télécharger l’image Open WebUI

Modification
docker pull ghcr.io/open-webui/open-webui:main
Pourquoi : Le tag main est l’image standard recommandée par Open WebUI et correspond au principe du Golden Build historique.
Résultat attendu : L’image est téléchargée sans erreur.

12.8 · Enregistrer l’image réellement installée

Lecture seule
docker image inspect ghcr.io/open-webui/open-webui:main \
  --format '{json .RepoDigests}'
Pourquoi : Le tag main évolue. Le digest permet de documenter précisément la version utilisée pour votre installation Golden.
Résultat attendu : Un digest d’image est affiché. Conservez-le dans votre inventaire privé, sans le considérer comme un secret.

12.9 · Créer le volume persistant

Modification
docker volume create open-webui
docker volume inspect open-webui --format '{.Name}'
Pourquoi : Les utilisateurs, chats, paramètres, uploads et données vectorielles doivent survivre à la suppression/recréation du conteneur.
Résultat attendu : Le volume open-webui existe.

12.10 · Démarrer Open WebUI

Modification
docker run -d \
  --name open-webui \
  --restart always \
  --add-host=host.docker.internal:host-gateway \
  -p METTRE_VOTRE_IP_LAN_JARVIS:3000:8080 \
  -v open-webui:/app/backend/data \
  --env-file ~/.config/jarvis/open-webui.env \
  ghcr.io/open-webui/open-webui:main
Pourquoi : Cette commande conserve les données, utilise une clé stable et lie l’interface uniquement à l’adresse LAN que vous avez choisie pour Jarvis.
Résultat attendu : Docker retourne l’identifiant du conteneur puis open-webui passe à l’état Up.

12.11 · Vérifier le conteneur

Validation
docker ps --filter name=open-webui
docker logs --tail 80 open-webui
Pourquoi : Vérifier le démarrage de l’application et détecter immédiatement une erreur de base de données ou de permissions.
Résultat attendu : Le conteneur est actif et aucun message d’erreur bloquant n’apparaît.

12.12 · Tester le endpoint de santé

Validation
curl -fsS http://METTRE_VOTRE_IP_LAN_JARVIS:3000/health
Pourquoi : Open WebUI fournit un endpoint /health sans authentification pour vérifier l’état de base de l’application.
Résultat attendu : Réponse HTTP correcte indiquant que le service est disponible.

12.13 · Vérifier le binding réseau

Validation
ss -lnt | grep ':3000 '
docker port open-webui
Pourquoi : Vérifier que le port n’a pas été publié involontairement sur toutes les interfaces.
Résultat attendu : Le port 3000 est associé à l’adresse LAN choisie pour Jarvis, pas à une exposition Internet non contrôlée.

12.14 · Ouvrir l’interface Web

Modification
http://METTRE_VOTRE_IP_LAN_JARVIS:3000
Pourquoi : Le premier compte créé devient généralement l’administrateur de l’instance.
Résultat attendu : L’écran initial Open WebUI s’affiche et vous pouvez créer votre compte local.

12.15 · Ajouter Hermes comme connexion OpenAI-compatible

Modification

Dans Open WebUI

  1. Ouvrir Settings → Admin → Connections.
  2. Ajouter une connexion de type OpenAI-compatible.
  3. URL : http://METTRE_VOTRE_IP_LAN_JARVIS:8642/v1.
  4. API Key : METTRE_VOTRE_CLE_API_HERMES.
  5. Enregistrer puis utiliser la fonction de vérification de connexion.
Pourquoi : Hermes expose une API compatible OpenAI ; Open WebUI peut donc le considérer comme un provider de modèles.
Résultat attendu : La connexion est validée et le modèle hermes-agent apparaît dans la liste.

12.16 · Vérifier la chaîne complète depuis l’interface

Validation

Test conseillé

  1. Sélectionner hermes-agent.
  2. Créer une nouvelle conversation.
  3. Envoyer : « Donne-moi l’état d’Ollama. Lecture uniquement. »
  4. Vérifier que la réponse provient bien d’Hermes et que les règles d’approbation du Module 07 restent actives.
Résultat attendu : Open WebUI affiche une réponse complète fournie par Hermes, sans contournement des garde-fous.

12.17 · Vérifier la persistance des données

Validation
docker exec open-webui sh -lc 'test -f /app/backend/data/webui.db && echo "webui.db present"'
docker volume inspect open-webui --format '{.Name}'
Pourquoi : La base Open WebUI et le volume Docker sont des éléments critiques du futur backup.
Résultat attendu : webui.db est présent et le volume open-webui existe.

12.18 · Tester un redémarrage du conteneur

Validation
docker restart open-webui
sleep 5
curl -fsS http://METTRE_VOTRE_IP_LAN_JARVIS:3000/health
Pourquoi : Vérifier que l’interface, la base et la clé persistante survivent à un redémarrage normal.
Résultat attendu : Open WebUI revient en ligne et votre compte/configuration est conservé.

12.19 · Vérifier la politique de redémarrage Docker

Validation
docker inspect open-webui \
  --format '{.HostConfig.RestartPolicy.Name}'
Pourquoi : Le conteneur doit revenir automatiquement après un redémarrage de Docker ou de la machine.
Résultat attendu : La politique affichée est always.

12.20 · Vérifier les logs après le test complet

Validation
docker logs --tail 150 open-webui | grep -Ei 'error|exception|failed|traceback' || true
Pourquoi : Un service peut sembler fonctionnel tout en accumulant des erreurs de provider ou de base de données.
Résultat attendu : Aucun message d’erreur bloquant lié à Open WebUI ou à la connexion Hermes.

Sécurité et exposition réseau

LAN uniquement

Le Golden Build lie Open WebUI à METTRE_VOTRE_IP_LAN_JARVIS. Ne remplacez pas ce choix par une exposition globale sans raison et sans protection supplémentaire.

Accès distant

Pour un téléphone ou un ordinateur hors domicile, utilisez votre VPN privé puis ouvrez l’adresse LAN de Jarvis. N’ouvrez pas directement le port Web sur Internet.

Compte administrateur

Protégez le premier compte créé avec un mot de passe robuste. Ne publiez jamais les identifiants dans la documentation ou un dépôt Git.

Clé Hermes

La clé API Hermes ne doit pas apparaître dans un fichier HTML, une capture publique ou un script partagé. Elle est saisie uniquement dans votre instance privée Open WebUI.

Ce qui doit être sauvegardé plus tard

Volume Open WebUI

Le Module 16 sauvegardera le contenu complet de /app/backend/data : base SQLite, uploads, vector store et autres données persistantes.

Secret WebUI

Conservez ~/.config/jarvis/open-webui.env dans une sauvegarde privée et chiffrée. Sans la même clé, certaines données sensibles peuvent devenir illisibles après reconstruction.

Image / digest

Conservez le digest de l’image réellement utilisée pour pouvoir reproduire ou diagnostiquer une installation Golden.

Attention à docker inspect

Une sortie complète de docker inspect peut contenir des variables d’environnement sensibles. Ne publiez jamais un inspect brut dans une documentation publique.

Mise à jour future

Principe

  1. Sauvegarder le volume Open WebUI avant toute mise à jour.
  2. Télécharger la nouvelle image.
  3. Noter son digest.
  4. Recréer le conteneur avec le même volume et le même secret.
  5. Valider /health puis une conversation Hermes.
Ne faites jamais : docker volume rm open-webui pour « nettoyer » une mise à jour. Cela supprime les données persistantes de l’interface.

Dépannage rapide

Le conteneur ne démarre pas

Lisez docker logs open-webui, puis vérifiez le volume, le fichier d’environnement et le port 3000.

L’interface répond mais pas Hermes

Testez d’abord l’API Hermes depuis Jarvis. Vérifiez ensuite que l’URL OpenAI-compatible contient bien /v1 et que la clé API utilisée est celle d’Hermes.

Aucun modèle disponible

Vérifiez l’endpoint /v1/models du Gateway Hermes et la connexion configurée dans Admin → Connections.

Déconnexion après recréation

Vérifiez que le même WEBUI_SECRET_KEY est réutilisé et que le fichier open-webui.env n’a pas été régénéré par erreur.

Perte des chats

Contrôlez que le volume open-webui est toujours monté sur /app/backend/data. Ne créez pas un nouveau volume au hasard.

Port accessible depuis Internet

Corrigez immédiatement le binding Docker et les règles réseau. Le Golden Build prévoit un accès privé LAN/VPN uniquement.

Références officielles

Validation du Module 12

Ne passez au module suivant que lorsque tous les points applicables sont validés.

Docker est opérationnel.
L’API Hermes répond avant l’installation.
Le fichier de secret Open WebUI existe en permissions 600.
L’image Open WebUI est téléchargée.
Le volume open-webui existe.
Le conteneur open-webui est actif.
Le endpoint /health répond.
Le port Web est lié à l’adresse LAN choisie.
Le compte administrateur local est créé.
Hermes est configuré comme provider OpenAI-compatible.
hermes-agent est visible et répond dans Open WebUI.
Le volume contient webui.db.
La configuration survit au redémarrage du conteneur.
La politique de redémarrage Docker est always.
Open WebUI n’est pas exposé directement sur Internet.
Les logs ne montrent aucune erreur bloquante.

STOP — Module 12 validé

Jarvis dispose maintenant d’une interface Web privée et persistante connectée à Hermes Agent. Le prochain module configurera Gmail via Himalaya.

← Module précédentRevenir à l’ordre des modules