Open WebUI évolue vite, et la tentation est grande de lancer un docker pull sans réfléchir. Dans la plupart des cas, cela se passe bien, parce que vos données vivent dans un volume Docker et non dans le conteneur. Mais « la plupart des cas » ne suffit pas quand l'instance contient les conversations de toute une équipe, des bases de connaissances et des comptes. Ce tutoriel détaille une procédure sûre : comprendre où sont les données, sauvegarder, mettre à jour avec docker run ou Docker Compose, vérifier, puis savoir revenir en arrière si une migration se passe mal.
Il suppose que vous avez déjà une instance en service et un accès au terminal de votre serveur. Si ce n'est pas le cas, commencez par installer Open WebUI avec Docker sur un VPS Linux. Les commandes ci-dessous s'appuient sur la documentation officielle de mise à jour d'Open WebUI.
Comprendre où sont vos données
Un conteneur Docker est jetable : on le supprime et on le recrée à partir d'une image. Ce qui doit survivre est stocké dans un volume, c'est-à-dire un espace de stockage géré par Docker et séparé du système de fichiers du conteneur. Pour Open WebUI, la documentation indique un volume nommé open-webui, monté dans le conteneur sur /app/backend/data. On y trouve la base de données, les comptes utilisateurs, l'historique des conversations, les fichiers téléversés et les réglages enregistrés depuis l'interface.
Conséquence directe : mettre à jour revient à remplacer l'image et le conteneur, en gardant le volume. Les deux erreurs classiques sont de lancer le nouveau conteneur sans le montage du volume (vous obtenez une instance vierge, les anciennes données restent orphelines dans l'ancien volume) ou de supprimer le volume par réflexe en « nettoyant ».
| Élément | Où il se trouve | Survit à la recréation du conteneur ? |
|---|---|---|
| Base, comptes, conversations, fichiers | Volume open-webui | Oui, si le volume est monté |
| Version d'Open WebUI | Image Docker (tag) | Non, c'est ce que l'on change |
| Variables d'environnement | Commande docker run ou fichier Compose | Seulement si vous les redéfinissez |
Clé WEBUI_SECRET_KEY | Variable d'environnement | Seulement si elle est fixée |
Prérequis : terminal, SSH et sudo
Toutes les commandes de ce tutoriel se tapent dans un terminal, la fenêtre qui affiche le shell : l'interpréteur de commandes qui exécute vos instructions. Sur un serveur, vous vous y connectez en SSH, le protocole chiffré d'accès distant à une machine Linux. Linux appartient à la famille des systèmes Unix, et des distributions comme Ubuntu ou Debian partagent ce mode de fonctionnement en ligne de commande.
Pour les tâches d'administration, la commande sudo exécute une action avec les droits du superutilisateur (root) pour un compte autorisé, sans ouvrir de session root permanente. Un VPS Linux ou un serveur dédié vous donne ce niveau d'accès, indispensable pour gérer Docker, les volumes et les sauvegardes.
Avant de toucher aux volumes, vérifiez deux ressources. L'espace disque libre d'abord : df -h affiche l'occupation de chaque partition. Puis la mémoire vive (RAM) : free -h indique ce qui reste disponible pendant que le conteneur redémarre. Docker isole vos applications dans des conteneurs, une forme de virtualisation légère au niveau du système, différente d'une machine virtuelle. Gardez aussi à jour le système et les paquets de votre distribution, indépendamment de la mise à jour d'Open WebUI.
Lexique : image, conteneur, volume, tag et migration
Ces termes reviennent dans toute la procédure. Les connaître évite la plupart des erreurs de mise à jour.
| Terme | Définition | Exemple dans ce guide |
|---|---|---|
| Image Docker | Modèle figé qui contient l'application et ses dépendances, téléchargé avec docker pull. | ghcr.io/open-webui/open-webui |
| Conteneur | Instance en cours d'exécution créée à partir d'une image. Il se supprime et se recrée sans perte de données si le volume est conservé. | open-webui |
| Volume | Espace de stockage géré par Docker, séparé du conteneur. | open-webui, monté sur /app/backend/data |
| Tag | Étiquette qui désigne une version d'image, par exemple main ou vX.Y.Z. Changer de tag ne modifie pas le volume. | :main ou :vX.Y.Z |
| Migration | Modification du schéma de la base de données, exécutée au démarrage d'une nouvelle version. Un retour à l'ancien tag ne l'annule pas. | Contrôlée dans les journaux après la mise à jour |
| Reverse proxy | Serveur web placé devant l'application, qui reçoit les requêtes HTTPS et les transmet au conteneur. | Caddy, dans la section Compose |
Choisir son tag d'image
Avant même de mettre à jour, décidez de ce que vous suivez. Un tag est l'étiquette qui désigne une version précise d'une image Docker. Les tags décrits dans la documentation sont les suivants :
main: la dernière build. Pratique, mais elle peut apporter des changements cassants sans avertissement.vX.Y.Z: une version figée, recommandée pour une instance partagée ou de production.vX.Y.Z-cuda: version figée avec prise en charge CUDA.vX.Y.Z-ollama: version figée embarquant Ollama.dev: préversion, adaptée à une seconde instance de test avec son propre volume.
Notre conseil d'administrateur : sur un serveur utilisé par d'autres personnes, figez un tag de version et faites évoluer ce tag à la main, après avoir lu les notes de version sur la page des releases du projet. Gardez main pour un environnement de test. Si vous exécutez Ollama séparément, la mise à jour des modèles est indépendante : voir installer Ollama sur un VPS Linux.
Fixer WEBUI_SECRET_KEY avant tout
Sans clé persistante, chaque recréation du conteneur génère une nouvelle clé secrète, ce qui invalide toutes les sessions et déconnecte tout le monde. Ce n'est pas une perte de données, mais c'est déroutant pour vos utilisateurs. Générez la clé une seule fois :
openssl rand -hex 32
Copiez le résultat dans votre commande docker run ou dans la section environment de votre fichier Compose, et ne la changez plus. Stockez-la comme un secret : dans un gestionnaire de mots de passe ou un fichier .env aux droits restreints, jamais dans un dépôt public.
Sauvegarder le volume avant chaque mise à jour
C'est l'étape qui transforme une mise à jour risquée en opération réversible. La documentation propose d'archiver le volume avec un conteneur Alpine jetable :
docker run --rm -v open-webui:/data -v $(pwd):/backup \
alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz /data
Cette commande crée dans le répertoire courant une archive datée, par exemple openwebui-20261119.tar.gz. Vérifiez qu'elle existe et que sa taille est plausible :
ls -lh openwebui-*.tar.gz
tar tzf openwebui-20261119.tar.gz | head
Une sauvegarde qui reste sur le même disque que l'instance protège d'une mauvaise manipulation, pas d'une panne de machine. Une clé USB ou un disque externe peut servir de copie, à condition de la conserver hors de la machine. Copiez l'archive ailleurs, par exemple avec rsync vers un stockage distant, et chiffrez-la si elle contient des conversations sensibles : voir chiffrer ses sauvegardes hors site. Sur nos offres, les sauvegardes sont une option à souscrire à part : ne comptez pas dessus tant que vous ne l'avez pas activée, et gardez de toute façon votre propre copie de ce volume.
Mettre à jour avec docker run
Si vous avez lancé Open WebUI avec une commande docker run, la procédure documentée tient en trois temps.
- Supprimer le conteneur. Le volume est conservé :
docker rm -f open-webui - Télécharger l'image, avec
mainou un tag figé :docker pull ghcr.io/open-webui/open-webui:main - Recréer le conteneur avec le même volume et la même clé :
docker run -d -p 3000:8080 \ --add-host=host.docker.internal:host-gateway \ -v open-webui:/app/backend/data \ -e WEBUI_SECRET_KEY="votre-cle-secrete" \ --name open-webui --restart always \ ghcr.io/open-webui/open-webui:main
Si votre instance utilise le GPU NVIDIA, ajoutez --gpus all comme au premier lancement et utilisez le tag -cuda correspondant. Le point d'attention : relancez avec exactement les mêmes options que l'installation initiale (ports, variables, volume). Si vous ne vous souvenez plus de ce que vous aviez passé, inspectez le conteneur avant de le supprimer :
docker inspect open-webui --format '{{json .HostConfig.Binds}}'
docker inspect open-webui --format '{{json .Config.Env}}'
Mettre à jour avec Docker Compose
Avec Compose, c'est plus simple et plus reproductible, car toute la configuration est dans un fichier versionnable. Voici un exemple minimal avec un tag figé. Remplacez vX.Y.Z par une version réelle listée sur la page des releases du projet.
services:
open-webui:
image: ghcr.io/open-webui/open-webui:vX.Y.Z
container_name: open-webui
restart: always
ports:
- "127.0.0.1:3000:8080"
environment:
- WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}
volumes:
- open-webui:/app/backend/data
volumes:
open-webui:
Le port est lié à 127.0.0.1 pour que l'interface ne soit joignable que via un reverse proxy, par exemple Caddy en HTTPS devant Docker. Configurez la clé dans un fichier .env placé à côté du fichier Compose, que Compose lit automatiquement. Pour mettre à jour, modifiez le tag si vous êtes en version figée, puis :
docker compose pull
docker compose up -d
Compose détecte que l'image a changé, recrée le conteneur et réutilise le volume nommé. Pour accéder ensuite en HTTPS, il faut un nom de domaine dont l'enregistrement DNS pointe vers le serveur. Pour les bases de Compose, consultez Docker Compose sur un VPS Linux. Une règle d'or : n'ajoutez jamais l'option -v à docker compose down pendant une mise à jour, car elle supprime les volumes déclarés.
Vérifier après la mise à jour
Ne vous fiez pas au simple fait que le conteneur démarre. Suivez les journaux pendant la première minute : c'est là que s'exécutent les éventuelles migrations de base de données. Si le conteneur s'arrête, le message d'erreur se trouve dans ces mêmes journaux.
docker logs -f --tail 100 open-webui
docker ps --filter name=open-webui
Contrôlez ensuite ces points :
- le conteneur est à l'état
Upet ne redémarre pas en boucle ; - vous vous connectez avec un compte existant et retrouvez vos conversations ;
- vos connexions vers Ollama ou vers une API compatible fonctionnent toujours ;
- vos bases de connaissances et vos fichiers sont accessibles.
Après la mise à jour, videz le cache du navigateur avec Ctrl+F5 (ou Cmd+Shift+R sur macOS) : des ressources front-end obsolètes peuvent sinon provoquer des affichages incohérents qu'on prend à tort pour un bug de la nouvelle version.
Revenir en arrière : ce qui marche, et ce qui ne marche pas
C'est le piège le plus sous-estimé. Remettre un ancien tag dans votre fichier Compose n'annule pas une migration de base de données déjà exécutée. Si la nouvelle version a modifié le schéma, l'ancienne peut refuser de démarrer ou se comporter de façon imprévisible. La documentation est claire : si une migration a eu lieu, il faut restaurer une sauvegarde faite avant la mise à jour.
Restaurer la sauvegarde du volume
Attention, cette opération vide le volume avant d'extraire l'archive. Vérifiez deux fois le nom du fichier. Si votre utilisateur n'a pas les droits Docker, préfixez chaque commande par sudo.
docker stop open-webui
docker run --rm -v open-webui:/data -v $(pwd):/backup \
alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-AAAAMMJJ.tar.gz -C /"
docker start open-webui
Pour que la restauration soit cohérente, remettez aussi l'ancien tag d'image dans votre configuration, puis recréez le conteneur. Sinon, vous replacez d'anciennes données sous une version qui attend un schéma plus récent. Avec Compose, arrêtez d'abord le service, restaurez, rétablissez le tag, puis relancez :
docker compose stop open-webui
# restaurer l'archive comme ci-dessus, puis éditer le tag dans compose.yaml
docker compose up -d
Tester la restauration à blanc
Une sauvegarde jamais restaurée est une hypothèse, pas une garantie. Testez au moins une fois sur une instance annexe, avec un volume de test, avant d'en avoir besoin. C'est aussi le moment idéal pour essayer le tag dev sans toucher à la production.
Cas particuliers
Plusieurs réplicas
Si vous faites tourner plusieurs instances sur la même base, les mises à jour progressives ne sont pas prises en charge quand le schéma change. Arrêtez toutes les instances, laissez-en une seule effectuer la migration, puis redémarrez les autres sur la nouvelle version.
Mises à jour automatiques avec un outil tiers
Il existe des outils qui tirent automatiquement les nouvelles images. Sur une instance de production, nous déconseillons de les combiner avec le tag main : une migration irréversible pourrait s'exécuter en pleine nuit, sans sauvegarde préalable. Si vous automatisez, figez les versions, et si vous écrivez un script shell pour enchaîner les étapes, faites-le s'arrêter à la première erreur, planifiez la sauvegarde juste avant et surveillez le résultat, par exemple avec des tâches planifiées cron ou timers systemd.
Libérer l'espace des anciennes images
Chaque mise à jour laisse l'ancienne image sur le disque, et les images d'Open WebUI sont volumineuses. Une partition saturée peut bloquer la sauvegarde suivante, d'où l'intérêt de surveiller l'espace disque avec df -h. Une fois la nouvelle version validée, supprimez les images inutilisées :
docker image prune
Cette commande ne touche pas aux volumes. Pour aller plus loin sans risque, lisez nettoyer Docker avec prune sur un VPS Linux, et gardez en tête que docker volume prune peut supprimer un volume non rattaché à un conteneur à ce moment-là : ne le lancez jamais pendant que votre instance est arrêtée.
Checklist de mise à jour
- Lire les notes de version et repérer une éventuelle migration ou un changement cassant.
- Sauvegarder le volume
open-webuiet copier l'archive hors du serveur. - Vérifier que
WEBUI_SECRET_KEYest fixée dans la configuration. - Noter le tag actuel, pour pouvoir y revenir avec la sauvegarde.
- Exécuter
docker compose pullpuisdocker compose up -d, ou la séquencedocker run. - Lire les journaux, tester la connexion et les modèles, vider le cache du navigateur.
- Nettoyer les anciennes images une fois la version validée.
Où héberger Open WebUI
Pour héberger Open WebUI, administrer Docker, contrôler les volumes et planifier vos sauvegardes, il vous faut un accès root, ce que fournissent un VPS Linux ou un serveur dédié. Les serveurs de jeu gérés depuis le panel Pterodactyl n'offrent pas cet accès. Nos offres reposent sur du stockage SSD, avec un réseau jusqu'à 10 Gbit/s selon l'offre et une protection anti-DDoS, dans un datacenter à Paris.
FiveM
Minecraft
Rust
RedM
Hytale