Aller au contenu principal

Docker

Docker est la méthode de déploiement de type production la plus simple pour un serveur unique.

Pour une installation sur un serveur unique accessible depuis Internet, commencez par Déploiement distant privé. Son modèle Compose ne publie aucun port de l'application, utilise par défaut l'image main et ajoute une barrière Cloudflare Access externe, des contrôles de l'hôte, des sauvegardes et des limites de conteneurs.

Disponibilité de Work​

Work est activé par défaut dans les fichiers Compose du dépôt. L'image inclut l'interface en ligne de commande Docker et Compose monte /var/run/docker.sock ; les conteneurs des tâches Work sont donc des pairs du conteneur Libre WebUI. Ils apparaissent dans docker ps sur l'hôte.

Un processus qui accède à ce socket dispose d'un contrôle de l'hôte Docker équivalent à celui de l'utilisateur root. L'activation de Work par défaut est un choix délibéré : Work est une fonctionnalité essentielle qui ne peut pas fonctionner sans accès au démon. Par conséquent, chaque administrateur Libre WebUI est de fait administrateur de l'hôte. Tenez-en compte :

  • Conservez la pile sur un hôte dont vous faites déjà confiance aux administrateurs.
  • N'exposez pas le port publié à un réseau non fiable.
  • Retirez le montage de /var/run/docker.sock lorsque Work n'est pas nécessaire. La page Work indique alors Environnement d'exécution indisponible.

Sous Linux, le socket appartient au groupe docker plutôt qu'à root ; l'utilisateur non-root de l'application a donc besoin de l'identifiant de ce groupe. Définissez-le une fois :

echo "DOCKER_GID=$(docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
  alpine stat -c '%g' /var/run/docker.sock)" >> .env

Lisez-le au moyen d'un conteneur comme dans l'exemple. Un hôte macOS renvoie une valeur différente de celle que voit le conteneur, car Docker Desktop fait transiter le socket par une machine virtuelle. Si le groupe est incorrect, la page Work indique le problème au lieu d'échouer silencieusement. Consultez Work : espaces de travail isolés.

Les aperçus Work et l'ordinateur Work publient des ports aléatoires uniquement sur une interface privée de l'hôte. Docker Desktop fonctionne avec les valeurs par défaut de Compose : la boucle locale de l'hôte pour la liaison et host.docker.internal pour la connexion du backend. Docker Engine natif ne peut pas atteindre un service en écoute sur la boucle locale de l'hôte depuis un conteneur voisin. Liez plutôt les ports à la passerelle non publique de son pont Docker :

echo "WORK_PREVIEW_BIND=$(docker network inspect bridge \
  --format '{{(index .IPAM.Config 0).Gateway}}')" >> .env
echo "WORK_DOCKER_PUBLISHED_HOST=host.docker.internal" >> .env
docker compose up -d --force-recreate libre-webui

Les fichiers Compose associent host.docker.internal à host-gateway. N'utilisez jamais WORK_PREVIEW_BIND=0.0.0.0 : cela publierait sur toutes les interfaces de l'hôte des ports de tâches éphémères non authentifiés, au lieu de les garder derrière le proxy signé de Libre WebUI.

Ollama inclus​

Exécute Libre WebUI et Ollama dans une même pile Compose :

docker compose up -d

Ouvrez http://localhost:8080.

Par défaut, le port de la WebUI est lié à l'interface de bouclage de l'hôte. Définissez WEBUI_BIND_ADDRESS=0.0.0.0 uniquement lorsqu'un réseau local de confiance ou un proxy inverse de l'hôte doit y accéder, et limitez le port à l'aide du pare-feu de l'hôte.

Ollama reste privé sur le réseau Compose. Pour le rendre accessible aux applications de l'hôte sur l'interface de bouclage, ajoutez la substitution explicite pour l'hôte :

docker compose -f docker-compose.yml -f docker-compose.ollama-host.yml up -d

Ne définissez OLLAMA_BIND_ADDRESS que lorsqu'une autre machine doit accéder à Ollama et protégez ce port par un pare-feu et un proxy capable d'assurer l'authentification.

GPU NVIDIA​

Utilisez le fichier Compose pour GPU lorsque Docker a accès à l'environnement d'exécution NVIDIA :

docker compose -f docker-compose.gpu.yml up -d

Vérifiez l'accès au GPU depuis le conteneur Ollama si les modèles s'exécutent encore sur le CPU.

Ollama externe​

Utilisez cette configuration lorsqu'Ollama s'exécute déjà sur l'hôte ou un autre serveur :

docker compose -f docker-compose.external-ollama.yml up -d

Remplacez l'URL d'Ollama si nécessaire :

OLLAMA_BASE_URL=http://192.168.1.10:11434 docker compose -f docker-compose.external-ollama.yml up -d

Work avec socket isolé​

Les fichiers Compose standard montent le socket Docker dans le conteneur Libre WebUI afin que Work puisse exécuter les conteneurs des tâches ; ce montage confère un contrôle de l'hôte Docker équivalent à celui de l'utilisateur root. Pour conserver Work sans donner le socket à l'application web, utilisez la variante avec proxy de socket :

docker compose -f docker-compose.socket-proxy.yml up -d

Un proxy de socket situé sur un réseau interne détient /var/run/docker.sock et ne transmet que les sections de l'API utilisées par Work (conteneurs, images, volumes, réseaux, exec, informations). Les points de terminaison Swarm, secrets, configurations, compilation et système sont refusés par le proxy. Libre WebUI y accède au moyen de DOCKER_HOST=tcp://docker-socket-proxy:2375 : aucun montage du socket, aucun DOCKER_GID, et le terminal interactif comme les diagnostics système fonctionnent sans changement. Consultez la documentation sur les espaces de travail pour comprendre ce que cette limite couvre ou non.

Persistance des données​

Libre WebUI stocke les données du serveur dans /app/backend/data à l'intérieur du conteneur. Les fichiers Compose montent ce chemin sous forme de volume nommé.

L'image utilise également ce chemin par défaut lorsqu'elle est lancée directement avec docker run ; les fichiers temporaires de contrôle préalable de la base de données restent séparés dans /app/backend/temp. Montez /app/backend/data chaque fois que le conteneur est susceptible d'être recréé.

En production, définissez des secrets stables :

JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters

Sauvegardez ensemble le volume de données et la clé de chiffrement.

Avant de supprimer un conteneur lancé directement depuis une ancienne image, vérifiez que /app/backend/data/.encryption_key existe ou notez la valeur configurée de ENCRYPTION_KEY. Les anciennes images pouvaient n'écrire une clé générée automatiquement que dans la couche du conteneur ; supprimer ce conteneur supprime aussi l'unique clé capable de déchiffrer sa base de données persistante.

Si vous exploitez un environnement d'exécution personnalisé prenant en charge Work, les fichiers de ses tâches résident dans des volumes nommés Docker distincts et ne sont pas inclus dans la sauvegarde normale de /app/backend/data.

Accès public​

Les fichiers Compose du dépôt lient la WebUI à l'interface de bouclage et définissent directement CORS_ORIGIN. Une valeur dans votre shell ou votre fichier .env ne remplace pas cette valeur littérale. Modifiez l'entrée libre-webui.environment ou enregistrez une substitution explicite dans compose.origin.yml :

services:
  libre-webui:
    environment:
      CORS_ORIGIN: https://your-domain.example
      BASE_URL: https://your-domain.example

Appliquez la substitution avec le fichier Compose du dépôt choisi :

docker compose -f docker-compose.yml -f compose.origin.yml up -d

Placez ensuite Libre WebUI derrière HTTPS à l'aide d'un proxy inverse ou d'un équilibreur de charge de plateforme. Définissez WEBUI_BIND_ADDRESS sur l'interface exacte dont ce proxy a besoin ; ne publiez pas le port sur toutes les interfaces, sauf si le pare-feu l'exige.

Le serveur distribue déjà le frontend compilé de manière efficace : les bundles hachés sous /js/ et /assets/ sont envoyés compressés en brotli ou en gzip avec une durée de cache immutable d'un an, tandis que index.html et le service worker sont marqués no-cache afin qu'une nouvelle version soit prise en compte au chargement suivant. Un proxy n'a pas besoin de recompresser ni de mettre en cache ces chemins ; laissez passer Accept-Encoding.

Commandes utiles​

docker compose ps
docker compose logs -f libre-webui
docker compose logs -f ollama
docker compose pull
docker compose up -d

Documentation connexe​