Variables d’environnement
Cette page répertorie les variables d’environnement destinées aux opérateurs que lisent actuellement le serveur dorsal, l’interface et les scripts de maintenance de Libre WebUI. Les témoins internes réservés aux tests sont volontairement omis.
Serveur dorsal
| Variable | Valeur par défaut | Rôle |
|---|---|---|
NODE_ENV | development | Mode d’exécution |
PORT | 3001 en développement, 8080 en production | Port HTTP du serveur dorsal |
TRUST_PROXY | non défini (0 dans Helm) | Nombre exact de sauts de proxy inverse fiables utilisé pour déterminer l’adresse du client |
CORS_ORIGIN | origines locales de développement | Origines de navigateur autorisées, séparées par des virgules |
SERVE_FRONTEND | non défini | Servir l’interface compilée depuis le serveur dorsal avec true |
DOCKER_ENV | non défini | Activer le comportement destiné à Docker avec true |
DATA_DIR | backend/data ; ~/.libre-webui dans le CLI empaqueté | Répertoire de données persistantes |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight ; cache utilisateur dans le CLI empaqueté | Espace temporaire pour une copie privée d’inspection au démarrage de la DB/WAL ; prévoyez la taille de la base et de son WAL |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads dans le répertoire temporaire du système | Espace temporaire des importations de plugins en cours |
PLUGINS_DIR | $DATA_DIR/plugins | Répertoire accessible en écriture des plugins installés ou personnalisés |
BASE_URL | http://localhost:3001 | URL de base utilisée pour les valeurs par défaut des rappels OAuth |
LOG_LEVEL | info (warn dans les tests) | Niveau de journalisation du serveur dorsal |
LOG_FORMAT | text | json active des journaux structurés d’une ligne avec horodatage, identifiants de corrélation et expurgation |
OTEL_EXPORTER_OTLP_ENDPOINT | non défini | Exportation facultative de télémétrie JSON OTLP/HTTP ; aucune télémétrie ne quitte le processus si non défini |
OTEL_EXPORTER_OTLP_HEADERS | non défini | En-têtes key=value envoyés au collecteur OTLP, séparés par des virgules (par exemple pour l’authentification) |
OTEL_SERVICE_NAME | libre-webui | Attribut de ressource service.name de la télémétrie exportée |
WEBUI_HOST | bouclage ; 0.0.0.0 dans Docker | Adresse d’écoute HTTP |
OPEN_BROWSER | true lorsque l’interface est servie | Définir false pour empêcher l’ouverture automatique du navigateur |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Limite de jetons du mode document intégral propre à chaque discussion (1000-2000000) |
GALLERY_RETENTION_DAYS | non défini (conservation illimitée) | Supprimer lors du passage du planificateur les médias de la galerie plus anciens que ce nombre de jours |
RECOVERY_DRILL_INTERVAL_HOURS | non défini (exercices désactivés) | Exécuter automatiquement un exercice de restauration vérifié toutes les N heures (profil individuel) |
RECOVERY_DRILL_HISTORY | 60 | Nombre d’entrées conservées dans l’historique des exercices de restauration |
Dans les lancements depuis les sources, les valeurs relatives DATA_DIR, PLUGINS_DIR et PLATFORM_PREFLIGHT_TMP_DIR sont ancrées au répertoire du serveur dorsal, indépendamment du répertoire de travail de l’environnement. Sans DATA_DIR — ou avec l’exemple récent DATA_DIR=./data — les commandes exécutées depuis la racine et l’espace de travail du serveur dorsal utilisent donc backend/data. Par compatibilité, une configuration source existante contenant DATA_DIR=./backend/data continue à sélectionner backend/backend/data ; ne la modifiez que dans le cadre d’une sauvegarde et d’une migration volontaire, application arrêtée. Un profil source sans valeur continue aussi d’utiliser backend/backend/data lorsqu’il s’agit du seul stockage durable existant. Si les deux emplacements contiennent un état et qu’aucun chemin n’est sélectionné, le démarrage échoue de manière sécurisée au lieu de deviner, copier ou fusionner.
Les lanceurs npx, npm global et Homebrew interactif conservent plutôt les données dans ~/.libre-webui. Une valeur DATA_DIR relative explicitement fournie à ce lanceur est résolue depuis le répertoire de travail de l’appelant et convertie en chemin absolu avant le démarrage du serveur dorsal. Une valeur PLUGINS_DIR relative explicitement configurée suit la même règle ; si elle est absente, les plugins accessibles en écriture restent sous $DATA_DIR/plugins. L’espace temporaire d’inspection utilise par défaut un cache accessible à l’utilisateur et situé hors du répertoire de données : ~/Library/Caches/libre-webui sous macOS, %LOCALAPPDATA%\libre-webui sous Windows ou ${XDG_CACHE_HOME:-~/.cache}/libre-webui sur les autres systèmes. Le service Homebrew fixe le même répertoire de données personnel et utilise var/libre-webui/preflight de Homebrew pour l’espace temporaire. Définissez explicitement PLATFORM_PREFLIGHT_TMP_DIR si ce cache ne peut pas contenir la base de données et son WAL. Les déploiements Docker et Helm fournis utilisent les chemins absolus /app/backend/data et /app/backend/temp/preflight, adossés à des montages distincts.
Socle de la plateforme
Le profil solo par défaut utilise SQLite, des objets binaires locaux chiffrés, des vecteurs intégrés chiffrés, une coordination locale et un processus de travail durable intégré. Le profil team utilise PostgreSQL, des objets binaires privés compatibles avec S3, PGVector, Redis et un processus de travail externe. La configuration d’équipe échoue de manière sécurisée : toutes les dépendances partagées doivent être sélectionnées ensemble.
| Variable | Valeur par défaut | Rôle |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Sélectionner le profil cohérent solo ou team |
DATABASE_BACKEND | sqlite | Sélectionner sqlite ou postgres |
DATABASE_URL | non défini | URL de connexion PostgreSQL, requise avec postgres |
DATABASE_SSL_MODE | verify-full | Politique TLS PostgreSQL : disable, require ou verify-full, qui vérifie le nom d’hôte |
POSTGRES_MIGRATION_MODE | apply | Exécuter les migrations compatibles sous verrou du responsable, ou validate pour une vérification du schéma en lecture seule |
POSTGRES_POOL_MAX | 10 | Nombre maximal de connexions PostgreSQL par processus d’application ou de travail (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Délai de connexion PostgreSQL (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Délai d’inactivité d’une connexion PostgreSQL (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Délai maximal d’une instruction PostgreSQL (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Durée d’attente du verrou du responsable des migrations (1-600000 ms) |
BLOB_STORE_BACKEND | local | Sélectionner le stockage local chiffré ou s3 privé |
VECTOR_STORE_BACKEND | embedded avec SQLite | Sélectionner les vecteurs embedded chiffrés ou pgvector |
COORDINATION_BACKEND | local en solo ; redis en équipe | Sélectionner la coordination locale au processus ou Redis |
REDIS_URL | non défini | URL redis: ou rediss:, requise avec la coordination Redis |
REDIS_KEY_PREFIX | libre | Espace de noms de 1 à 64 caractères pour les clés de coordination de Libre |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Délai de connexion initiale à Redis, plafonné à 60 secondes |
JOB_WORKER_MODE | embedded en solo ; external en équipe | Exécuter les gestionnaires dans l’application ou dans le processus de travail partagé autonome |
RESOURCE_LEASE_TTL_MS | 30000 | Durée de vie du bail de coordination pour la propriété des ressources des tâches durables (5000-300000 ; échec du démarrage hors plage) |
JOB_WORKER_CONCURRENCY | 4 | Tâches durables qu’un processus de travail peut exécuter simultanément (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Heures de conservation des événements de fragments diffusés avant leur suppression horaire |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Jours de conservation de tout événement durable avant sa suppression horaire |
PLATFORM_JOB_RETENTION_DAYS | 30 | Jours de conservation des tâches terminées hors cycle de vie avant leur suppression horaire |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | non défini | 1 ignore l’analyse approfondie des anciens textes chiffrés au prochain démarrage (échappatoire ; sinon mise en cache par génération de schéma) |
STORAGE_ENCRYPTION_KEYS | non défini | Liste secrète de clés JSON ; doit actuellement inclure legacy correspondant à ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | non défini | Identifiant de clé utilisé pour les nouvelles écritures d’objets binaires locaux et de vecteurs intégrés |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Maximum durable d’octets d’objets binaires en clair par propriétaire (entier positif sûr) |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Durée de vie d’une réservation de quota en diffusion abandonnée (au moins 60000 ms) |
S3_BUCKET | non défini | Compartiment privé compatible avec S3, requis avec s3 |
S3_REGION | non défini | Région S3, requise avec s3 |
S3_ENDPOINT | valeur par défaut du fournisseur | Point de terminaison HTTP(S) absolu facultatif pour MinIO ou un autre service compatible |
S3_ACCESS_KEY_ID | chaîne d’identifiants du SDK | Clé d’accès S3 explicite facultative |
S3_SECRET_ACCESS_KEY | chaîne d’identifiants du SDK | Requise lorsqu’une clé d’accès explicite est définie |
S3_SESSION_TOKEN | non défini | Jeton facultatif accompagnant les identifiants S3 explicites |
S3_FORCE_PATH_STYLE | false | Définir true pour les services exigeant un adressage par chemin |
S3_BLOB_PREFIX | libre/blobs | Préfixe opaque des clés du compartiment appartenant à Libre |
Lorsque la liste versionnée de clés de stockage est absente, les adaptateurs de stockage utilisent la valeur ENCRYPTION_KEY existante avec l’identifiant de clé legacy. Si elle aussi est absente, ils lisent le fichier ${DATA_DIR}/.encryption_key existant sans le générer ni le modifier. La configuration explicite et le fichier persistant doivent correspondre. Si une liste versionnée est introduite alors qu’une ancienne clé existe, conservez cette clé sous l’identifiant exact legacy jusqu’à ce que tous les objets et vecteurs aient été réécrits ou réencapsulés et vérifiés. Tout conflit, droit de fichier non sûr, lien symbolique ou clé configurée manquante provoque un échec sécurisé.
Redis sert à la coordination, pas à la persistance canonique. Le sélectionner seul ne rend pas SQLite, les fichiers locaux ou tout autre état appartenant au processus compatibles avec plusieurs répliques. En mode équipe, les limites de débit HTTP, les connexions Chat/WebSocket, les traitements STT/TTS/audio des fournisseurs, les importations d’archives et les sessions de terminal Work utilisent un contrôle d’admission partagé fondé sur Redis. Les capacités s’appliquent à l’ensemble des répliques, et non à chaque processus. Un échec d’admission ou de renouvellement de permis renvoie 503 ou interrompt l’opération en cours ; Libre ne revient jamais à un compteur local indépendant. Consultez Socle de la plateforme.
Le profil Compose d’équipe et le chart Helm fournis transmettent tous les sélecteurs et réglages de la plateforme d’équipe ci-dessus à l’application et au processus de travail externe. Dans le chart Helm, les sélecteurs non secrets se trouvent sous env ; définissez secrets.redisUrl, secrets.databaseUrl et secrets.storageEncryptionKeys pour les connexions et clés. Les limites du pool PostgreSQL s’appliquent par processus : prévoyez au moins (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX connexions à la base, plus une marge pour les opérateurs et les migrations. Conservez DATABASE_SSL_MODE=verify-full pour PostgreSQL géré ou distant. Seul le profil Compose d’équipe fourni sélectionne disable, car son écouteur de base de données est isolé sur le réseau privé du projet. Helm en mode équipe exige également une valeur secrets.jwtSecret stable et monte la même clé Secret dans tous les pods d’application et de traitement ; sans secret JWT, chaque processus générerait son propre matériel de signature. S3 reçoit des clés opaques et du texte chiffré ; les URL des compartiments et des fournisseurs ne sont pas stockées dans les métadonnées de l’application.
Les archives intégrées en mode solo et équipe conservent les paramètres du pool PostgreSQL et de ses délais, le délai de connexion à Redis, les deux paramètres de quota des objets binaires, les sélecteurs de plateforme et les paramètres d’adressage S3 dans leur configuration protégée, signée et chiffrée. Une restauration propre peut ainsi publier les valeurs opérationnelles nécessaires pour recréer le déploiement correspondant sans les placer en clair dans les métadonnées de l’archive.
Les paires application/processus de travail externe Compose et Helm d’équipe reçoivent les mêmes valeurs résolues OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT et OLLAMA_MAX_CONTEXT. Les appels aux fournisseurs pour les plongements de documents, les discussions durables et les exécutions Work ont lieu dans le processus de travail ; ces valeurs ne doivent donc pas diverger entre les processus. Les deux points d’entrée du serveur analysent les trois valeurs numériques comme des entiers positifs complets en base 10 avant de créer l’état local ou de se connecter à l’état partagé. Les valeurs partielles telles que 300000ms, la notation exponentielle ou hexadécimale, les valeurs hors limites et un délai d’opération longue inférieur au délai standard font échouer le démarrage.
Helm limite TRUST_PROXY à un nombre entier exact de sauts compris entre 0 et 16, et ne le transmet qu’aux pods d’application HTTP. Conservez la valeur par défaut 0 pour un trafic direct. Définissez le nombre fixe exact d’une chaîne Ingress/répartiteur de charge ; n’utilisez jamais la forme illimitée true de l’environnement d’exécution. Une valeur erronée regroupe les clients sous une adresse de proxy pour les limites de débit communes ou fait confiance à une adresse que le client peut fournir.
La compatibilité du schéma PostgreSQL exige une version exacte. L’application Helm et le processus de travail utilisent Recreate ; videz et arrêtez tous les anciens pods avant une mise à niveau d’équipe, puis laissez un nouveau processus migrer sous le verrou de responsable. N’exécutez pas plusieurs versions binaires simultanément et ne prétendez pas déployer le schéma sans interruption. Revenir en arrière signifie restaurer l’archive d’équipe vérifiée d’avant la mise à niveau dans des cibles PostgreSQL/S3 propres, avant de démarrer l’ancien binaire correspondant.
Une application d’équipe active exige worker.replicaCount >= 1 ; Helm refuse une application active sans processus de travail durable au lieu d’attendre l’échec de sa disponibilité. Définissez à zéro les nombres d’applications et de processus de travail pour une suspension complète. Un nombre d’applications nul avec un nombre de processus positif est un mode volontaire de vidage ou de récupération réservé au processus de travail ; il continue de consommer les tâches en attente sans servir de trafic web.
Outil de sauvegarde privée
Ces variables configurent deploy/private/libre-webui-backup et sont lues par le script de maintenance, pas par le processus de l’application :
| Variable | Valeur par défaut | Rôle |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Répertoire contenant le fichier Compose privé |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Répertoire protégé des ensembles de sauvegarde et du verrou |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Âge au-delà duquel les sauvegardes terminées sont supprimées |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Conteneur d’application déployé à inspecter |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Répertoire privé des clés de chiffrement et de signature des archives |
LIBRE_WEBUI_RESTORE_IMAGE | requis pour la restauration | Identifiant ou empreinte immuable vérifié de l’image Libre |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | chemin propre au volume sous /etc/libre-webui/restored | Nouveau répertoire de la configuration récupérée |
L’unité systemd charge les remplacements de sauvegarde depuis le fichier facultatif /etc/libre-webui/backup.env, appartenant à l’utilisateur racine. Définissez son mode sur 0600. Le répertoire de la pile, la durée de conservation, le nom du conteneur et le répertoire des clés de sauvegarde peuvent y être définis directement. L’environnement isolé du système de fichiers de l’unité n’autorise les écritures que sous le répertoire de sauvegarde par défaut. Une valeur LIBRE_WEBUI_BACKUP_DIR personnalisée exige aussi d’ajouter ce répertoire exact, créé au préalable, à une directive ReadWritePaths= de substitution du service ; consultez Déploiement distant privé.
Authentification et sécurité
| Variable | Valeur par défaut | Rôle |
|---|---|---|
ENABLE_SIGNUP | false | Autoriser les inscriptions après le premier administrateur local |
JWT_SECRET | généré/valeur de repli en développement | Secret de signature JWT ; à définir explicitement en production |
JWT_EXPIRES_IN | 7d | Durée de vie du jeton de session |
ENCRYPTION_KEY | générée automatiquement | Clé hexadécimale de 64 caractères pour les valeurs chiffrées |
DEBUG_ENCRYPTION | non défini | Journaliser les détails de débogage du chiffrement si défini |
TURNSTILE_SITE_KEY | non défini | Clé de site Cloudflare Turnstile pour la connexion et l’inscription |
TURNSTILE_SECRET_KEY | non défini | Clé secrète Cloudflare Turnstile pour la vérification du serveur dorsal |
TURNSTILE_EXPECTED_HOSTNAME | nom d’hôte de BASE_URL | Nom d’hôte requis dans la réponse de vérification de Cloudflare |
MFA_REQUIRED_MODE | non défini (bouton admin, optional) | Fixer la politique à deux facteurs sur optional ou required |
WEBAUTHN_RP_ID | nom d’hôte de la requête | Identifiant fixe de la partie utilisatrice pour les clés d’accès derrière plusieurs noms d’hôte |
VAPID_PUBLIC_KEY | générée et stockée chiffrée | Fixer la clé publique Web Push VAPID (point P-256 base64url) |
VAPID_PRIVATE_KEY | générée et stockée chiffrée | Fixer la clé privée Web Push VAPID (scalaire base64url) |
VAPID_SUBJECT | mailto:admin@localhost | Coordonnées de contact dans les autorisations Web Push signées |
Turnstile n’est activé que lorsque les deux clés Turnstile sont présentes.
ENABLE_SIGNUP=false autorise toujours le premier administrateur local dans une base de données vide, puis bloque les autres comptes locaux et OAuth. Avant le premier démarrage, protégez une route d’amorçage accessible à distance par une frontière d’identité externe.
Chaque JWT émis est lié à une session côté serveur (revendication sid) ; se déconnecter ou révoquer une session depuis Paramètres → Sessions invalide donc immédiatement le jeton sur toutes les répliques et ferme les connexions WebSocket actives. La conservation des journaux d’audit de sécurité est configurable :
| Variable | Valeur par défaut | Rôle |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Jours de conservation des lignes du journal d’audit de sécurité |
Authentification unique OIDC générique
Tout fournisseur OpenID Connect disposant d’un document de découverte peut être utilisé pour la connexion. Le parcours utilise PKCE (S256), un état CSRF et un nonce vérifié dans le jeton d’identification dont la signature est contrôlée. Les identités sont liées à la revendication stable sub.
| Variable | Valeur par défaut | Rôle |
|---|---|---|
OIDC_ISSUER_URL | non défini | URL de base de l’émetteur ; découverte depuis <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | non défini | Identifiant client OAuth enregistré auprès du fournisseur |
OIDC_CLIENT_SECRET | non défini | Secret client OAuth |
OIDC_DISPLAY_NAME | Single Sign-On | Libellé affiché sur le bouton de connexion |
OIDC_SCOPES | openid profile email | Portées demandées |
OIDC_CALLBACK_URL | BASE_URL + route de rappel OIDC | URI de redirection enregistrée auprès du fournisseur |
OIDC_ALLOWED_EMAIL_DOMAINS | non défini | Liste séparée par des virgules ; exige une adresse vérifiée dans l’un de ces domaines |
OIDC_GROUP_CLAIM | groups | Revendication du jeton d’identification contenant les noms des groupes |
OIDC_ADMIN_GROUPS | non défini | Liste séparée par des virgules ; le rôle admin suit l’appartenance aux revendications à chaque connexion |
OIDC_SYNC_GROUPS | false | true synchronise les groupes Libre avec la revendication de groupes à chaque connexion |
OIDC n’est activé que si l’URL de l’émetteur, l’identifiant client et le secret client sont tous présents. Une adresse e-mail déjà utilisée par un compte local non lié est refusée au lieu d’être fusionnée silencieusement, et la création d’un compte respecte toujours ENABLE_SIGNUP.
L’admission WebSocket de Chat peut être réglée sans affaiblir l’authentification :
| Variable | Valeur par défaut | Rôle |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Taille maximale acceptée d’un message WebSocket |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Nombre maximal de messages WebSocket par connexion |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Générations de fournisseur autorisées par compte |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Sockets authentifiés simultanés par compte |
WEBSOCKET_TICKET_TTL_MS | 30000 | Durée de vie du ticket Chat/Work à usage unique, plafonnée à 60 secondes |
Le navigateur échange son en-tête Authorization normal contre un ticket opaque et place uniquement cette valeur de courte durée dans l’URL de mise à niveau WebSocket. Les tickets sont à usage unique, liés au protocole et à la session, et ne sont stockés que sous forme de hachage. Les jetons de session durables n’apparaissent ainsi pas dans les journaux des cibles de requêtes du proxy inverse. Lorsque CORS_ORIGIN ou BASE_URL est configuré, les mises à niveau du navigateur comportant un en-tête Origin doivent correspondre à l’une de ces origines. Définissez-en au moins une pour un déploiement accessible à distance ; en l’absence des deux, le filtre Origin reste permissif par compatibilité avec le développement local. Les mises à niveau sans origine restent volontairement prises en charge pour Electron et les clients autres que les navigateurs, où le contrôle Origin des navigateurs n’existe pas. Elles exigent tout de même un ticket à usage unique valide et sont soumises aux mêmes vérifications actuelles du compte, de l’accès à Work et des tâches. Considérez le ticket comme la frontière d’authentification et limitez l’accès des clients non navigateur par les contrôles TLS, pare-feu et proxy inverse ordinaires du déploiement.
OAuth
| Variable | Rôle |
|---|---|
GITHUB_CLIENT_ID | Identifiant client OAuth GitHub |
GITHUB_CLIENT_SECRET | Secret client OAuth GitHub |
GITHUB_CALLBACK_URL | Remplacement de l’URL de rappel GitHub |
HUGGINGFACE_CLIENT_ID | Identifiant client OAuth Hugging Face |
HUGGINGFACE_CLIENT_SECRET | Secret client OAuth Hugging Face |
HUGGINGFACE_CALLBACK_URL | Remplacement de l’URL de rappel Hugging Face |
Si les URL de rappel ne sont pas définies, Libre WebUI construit leurs valeurs par défaut à partir de BASE_URL.
Ollama
| Variable | Valeur par défaut | Rôle |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | URL de base de l’API Ollama |
OLLAMA_TIMEOUT | 300000 | Délai des requêtes Ollama standard (1,000-3,600,000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Délai des opérations longues (1,000-3,600,000 ms, au moins OLLAMA_TIMEOUT) |
OLLAMA_MAX_CONTEXT | 32768 | Contexte maximal du modèle adopté automatiquement (128-2,097,152 jetons) |
Recherche web
| Variable | Valeur par défaut | Rôle |
|---|---|---|
SEARXNG_URL | non défini | Point de terminaison SearXNG par défaut du paramètre de recherche web ; un administrateur doit encore l’activer dans Paramètres > Recherche |
Libre Claw
| Variable | Valeur par défaut | Rôle |
|---|---|---|
LIBRE_CLAW_BASE_URL | http://127.0.0.1:8766 | URL facultative du démon Libre Claw |
LIBRE_CLAW_TIMEOUT_MS | 30000 | Délai d’une requête HTTP Libre Claw |
Environnement d’exécution Work
Ces variables configurent l’exécution de Work sur la machine ou le cluster Kubernetes qui héberge le serveur dorsal de Libre WebUI. Docker est l’environnement par défaut ; le chart Helm sélectionne Kubernetes avec work.enabled=true.
| Variable | Valeur par défaut | Rôle |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Image fixée utilisée pour les environnements isolés Work |
WORK_DOCKER_COMMAND | docker | Exécutable CLI du serveur dorsal Docker accessible au processus |
WORK_COMMAND_TIMEOUT_MS | 120000 | Délai par défaut ; un outil peut demander jusqu’à 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | Limite des sorties stdout/stderr capturées, appliquée à chaque flux |
WORK_MAX_AGENT_ROUNDS | 48 | Nombre maximal d’étapes modèle/outil d’une exécution, indépendant du fournisseur |
WORK_STATUS_BLURB_MODEL | 1 | Définir 0 pour éviter l’unique requête au modèle qui rédige la ligne d’état d’un agent dans la barre latérale après une exécution |
WORK_MEMORY_LIMIT | 2g | Limite de mémoire transmise à chaque conteneur Work |
WORK_CPU_LIMIT | 2 | Limite de processeur transmise à chaque conteneur Work |
WORK_PIDS_LIMIT | 256 | Limite de processus transmise à chaque conteneur Work |
WORK_PREVIEW_PORT | 4173 | Port que doit utiliser le serveur d’aperçu dans le conteneur de tâche |
WORK_PREVIEW_BIND | 127.0.0.1 | Interface hôte où est publié le port d’aperçu d’une tâche ; les déploiements Compose sur Docker Engine natif doivent utiliser une interface de pont non publique et joignable |
WORK_DOCKER_PUBLISHED_HOST | valeur par défaut de l’application : identique à WORK_PREVIEW_BIND ; valeur par défaut de Compose : host.docker.internal | Hôte/IP visible du serveur dorsal pour les ports d’aperçu, d’écran et d’audio publiés par Docker |
WORK_COMPUTER_SCREEN_PORT | 6080 | Port du conteneur de la passerelle d’écran de Work Computer (websockify) dans les environnements avec interface graphique |
WORK_COMPUTER_AUDIO_PORT | 6081 | Port du conteneur de la passerelle audio de Work Computer (websockify → moniteur PulseAudio) dans les environnements avec interface graphique |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Tâches simultanées avec environnement d’exécution pour toute l’instance |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Tâches simultanées avec environnement d’exécution pour un utilisateur |
WORK_MAX_TASKS_GLOBAL | 500 | Nombre maximal de tâches Work persistantes dans toute l’instance |
WORK_MAX_TASKS_PER_USER | 100 | Nombre maximal de tâches Work persistantes pour un administrateur |
WORK_NETWORK_NAME | libre-webui-work | Réseau de pont géré des environnements isolés pour les tâches en réseau |
WORK_RUN_LEASE_WAIT_MS | 60000 | Durée d’attente du bail d’exécution partagé de la tâche avant de signaler un conflit de réplique (mode équipe) |
WORK_RUNTIME_DNS | non défini | Adresses IP de résolveurs imposées aux tâches en réseau, séparées par des virgules |
WORK_DOCKER_SOCKET | DOCKER_HOST si unix:// ou tcp://, sinon /var/run/docker.sock | Point de terminaison Docker Engine des terminaux et diagnostics |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Terminaux de navigateur simultanés rattachés à une tâche |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Délai d’inactivité avant la fermeture d’une session de terminal |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 0 (désactivé) | Arrêter un environnement isolé après cette durée d’inactivité (aperçus compris) |
WORK_HOST_WORKSPACES_ENABLED | false | Autoriser une tâche à utiliser un dossier de l’hôte plutôt qu’un volume |
WORK_HOST_WORKSPACE_ROOTS | répertoire personnel de l’utilisateur du serveur | Racines, séparées par :, dans lesquelles doit résider un espace de travail de l’hôte |
WORK_RUNTIME_BACKEND | docker | Serveur dorsal des environnements isolés : docker ou kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Espace de noms contenant les pods et PVC des environnements Kubernetes |
WORK_K8S_STORAGE_CLASS | valeur par défaut du cluster | StorageClass des PVC des espaces de travail |
WORK_K8S_WORKSPACE_SIZE | 5Gi | Taille du PVC propre à chaque tâche (véritable quota de disque) |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Attente du passage d’un pod isolé à l’état Running (téléchargements compris) |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Attente de la disparition d’un pod isolé supprimé |
AGENT_CLI_MODELS_ENABLED | non défini (bouton admin, désactivé) | Fixer l’activation de la fonctionnalité Agents ; sinon bouton de Gestion des utilisateurs, désactivé par défaut |
TOOLS_ACCESS_MODE | non défini (bouton admin, administrateurs uniquement) | Fixer les outils de discussion sur admins ou all-users et verrouiller le bouton de Gestion des utilisateurs |
STT_ACCESS_MODE | non défini (bouton admin, tous les utilisateurs) | Fixer la reconnaissance vocale sur admins ou all-users et verrouiller le bouton |
TTS_ACCESS_MODE | non défini (bouton admin, tous les utilisateurs) | Fixer la synthèse vocale sur admins ou all-users et verrouiller le bouton |
VOICE_MODE_ACCESS_MODE | non défini (bouton admin, tous les utilisateurs) | Fixer le mode vocal mains libres sur admins ou all-users et verrouiller le bouton |
VOICE_CLONING_ACCESS_MODE | non défini (bouton admin, tous les utilisateurs) | Fixer le clonage vocal sur admins ou all-users et verrouiller le bouton |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | non défini | Noms d’hôte exacts que les serveurs d’outils et webhooks peuvent résoudre en adresses privées (séparés par des virgules) ; fixés |
AGENT_CLI_TIMEOUT_MS | 600000 | Durée d’exécution d’un CLI agent avant son arrêt |
CODEX_OAUTH_MODELS_ENABLED | true | Proposer le fournisseur Codex (ChatGPT) aux administrateurs |
CODEX_HOME | ~/.codex | Emplacement où sont lus les identifiants du CLI Codex (auth.json) |
Les binaires des CLI d’agents et les identifiants OAuth Codex sont propres au nœud. Ils ne sont pris en charge que dans un processus individuel, où la découverte et l’exécution voient le même système de fichiers et le même environnement. Le mode équipe exécute les tâches de discussion durables dans un processus de travail externe ; il exige donc AGENT_CLI_MODELS_ENABLED=false et CODEX_OAUTH_MODELS_ENABLED=false. Le démarrage refuse toute autre valeur au lieu d’annoncer un fournisseur qui pourrait n’exister que sur une réplique de l’application. Utilisez Ollama ou un plugin fournisseur dont les identifiants et le routage sont stockés dans PostgreSQL partagé ou transmis à l’identique à chaque application et processus de travail.
Avec le serveur dorsal Docker, un espace de travail de l’hôte monte un véritable répertoire sur /workspace. La tâche peut ainsi lire et écrire directement ces fichiers au lieu d’utiliser son propre volume Docker. Kubernetes refuse les espaces de travail correspondant à des dossiers de l’hôte. Cela réduit volontairement l’isolation Docker : conservez WORK_HOST_WORKSPACES_ENABLED désactivé si vous n’en avez pas besoin et limitez WORK_HOST_WORKSPACE_ROOTS autant que possible. Les chemins demandés sont résolus à travers les liens symboliques avant leur vérification par rapport aux racines, et les dossiers comme .ssh, .gnupg, .aws et .config sont toujours refusés.
Les modèles de CLI d’agents exposent comme modèles de discussion sélectionnables les agents de programmation déjà installés sur le serveur (claude, codex). Un agent sur abonnement peut donc répondre sans clé d’API. Seuls les administrateurs les voient ; le CLI s’exécute comme l’utilisateur serveur de Libre WebUI et hérite de ses identifiants d’agent. Considérez cela comme l’octroi à ces agents d’un accès à l’environnement de commande.
Sous Docker, les tâches Work en réseau rejoignent le pont géré WORK_NETWORK_NAME, créé avec les communications entre conteneurs désactivées afin qu’un environnement isolé ne puisse pas atteindre un autre environnement ni les conteneurs du déploiement. WORK_RUNTIME_DNS est le point d’intégration pris en charge de la politique de sortie Docker : dirigez-le vers un résolveur filtrant pour appliquer des listes d’autorisation ou de refus par nom. Les entrées qui ne sont pas des adresses IPv4/IPv6 sont refusées et consignées. Le filtrage DNS ne limite pas les sorties directement par adresse IP ; ajoutez des règles de pare-feu de l’hôte si le déploiement l’exige. Le serveur dorsal Kubernetes utilise plutôt les NetworkPolicies de refus par défaut du chart et les valeurs work.networkPolicy.blockedEgressCidrs.
Sous Docker, le terminal interactif et les diagnostics système communiquent directement avec l’API Docker Engine. Ils suivent WORK_DOCKER_SOCKET si elle est définie, sinon DOCKER_HOST — soit un socket unix://, soit un point de terminaison tcp:// HTTP simple comme un proxy de socket (consultez docker-compose.socket-proxy.yml) — puis /var/run/docker.sock à défaut. Une valeur DOCKER_HOST que ce client ne sait pas utiliser (ssh://, ou tcp:// avec DOCKER_TLS_VERIFY) signale que le terminal et les diagnostics Docker sont indisponibles ; le reste de Work continue de fonctionner par le CLI Docker, qui comprend lui-même ces points de terminaison. Sous Kubernetes, le terminal utilise la sous-ressource exec des pods et aucun point de terminaison Docker.
Work lit ces valeurs au démarrage du serveur dorsal. Le port d’aperçu est interne au conteneur de la tâche ; Libre WebUI le publie sur un port de bouclage attribué dynamiquement au lieu d’exposer directement cette valeur sur toutes les interfaces de l’hôte.
Conservez une image d’exécution fixée à une version ou une empreinte vérifiée. Augmenter le parallélisme ou les limites de ressources augmente la capacité d’exécution que peuvent consommer une ou plusieurs exécutions autonomes. WORK_MAX_AGENT_ROUNDS s’applique de la même manière aux exécutions reposant sur Ollama et sur des plugins ; il n’existe aucune limite inférieure propre aux plugins. Le budget de sécurité des appels d’outils vaut max(128, WORK_MAX_AGENT_ROUNDS × 8). Lorsqu’une exécution épuise son budget d’étapes, Work demande au modèle une transmission finale sans outils et se termine dans l’état terminal needs_input, plutôt que de renvoyer une erreur brute de limite ou de prétendre avoir réussi. Une exécution de suivi reprend dans le même espace durable. Les sorties d’outils persistantes ont une limite distincte d’environ 20,000 caractères sources, plus un marqueur de troncature.
Ces variables règlent un environnement Work déjà accessible. Les déploiements Compose du dépôt à instance unique l’activent par défaut : l’image contient le CLI Docker et ces fichiers Compose montent le socket Docker de l’hôte. Deux variables propres à Compose contrôlent ce câblage :
| Variable | Valeur par défaut | Rôle |
|---|---|---|
DOCKER_GID | 0 | Identifiant de groupe du socket Docker hôte, ajouté à l’utilisateur du conteneur |
DOCKER_SOCKET | /var/run/docker.sock | Chemin hôte du socket Docker à monter |
DOCKER_GID doit être le groupe du socket tel qu’il apparaît dans un conteneur ; un hôte macOS indique une autre valeur. La base Compose d’équipe ne monte aucun socket et garde Work avec Docker indisponible tant que docker-compose.team.work.yml n’est pas ajouté. Cette couche de production fournit à l’application et au processus de travail le même point de terminaison interne d’un proxy filtrant, jamais un montage de socket ni un groupe de socket. Le proxy n’autorise que les sections de l’API Docker utilisées par l’environnement, mais la création de conteneurs reste un identifiant de contrôle de l’hôte Docker ; utilisez un démon Work dédié ou sans privilèges racine pour une frontière plus robuste. Le chart Helm ne monte jamais le socket d’exécution d’un nœud. Activez son serveur dorsal Work natif fondé sur pods et PVC avec work.enabled=true.
Le profil solo doit conserver zéro ou une réplique d’application, car il utilise SQLite, des fichiers locaux et une coordination propre au processus. Le chart Helm accepte zéro pour une suspension volontaire et refuse les nombres supérieurs ou la mise à l’échelle automatique en mode solo. Un profil team complet peut utiliser plusieurs répliques d’application et un processus de travail externe, car PostgreSQL, S3, PGVector et Redis possèdent l’état partagé. Les pods des environnements isolés Work sont mis à l’échelle indépendamment dans les deux profils ; en mode équipe, le processus externe reçoit la même image Kubernetes, la même StorageClass et les mêmes limites work.env que les pods d’application.
Les fichiers Compose du dépôt acceptent aussi WEBUI_BIND_ADDRESS (valeur par défaut 127.0.0.1) et WEBUI_PORT (valeur par défaut 8080). Conservez l’adresse de bouclage par défaut, sauf si un réseau local fiable ou un proxy inverse de l’hôte doit joindre le port.
Découverte des modèles des fournisseurs
Le catalogue de modèles d’un fournisseur est redécouvert automatiquement lorsqu’il manque ou devient obsolète ; une actualisation reflète ainsi les modèles actuellement servis par le fournisseur. Ces variables règlent ce cycle :
| Variable | Valeur par défaut | Rôle |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Âge auquel le catalogue stocké est actualisé lors de la prochaine lecture de la liste des plugins |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Intervalle minimal entre les tentatives, afin de ne pas interroger souvent un fournisseur en échec |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Durée pendant laquelle une réponse de liste de plugins attend les actualisations |
Une actualisation qui dépasse ce délai continue de s’exécuter et sera servie à la requête suivante. Une action explicite Actualiser les modèles contacte toujours le fournisseur et ignore l’intervalle.
Clés des plugins fournisseurs
Les plugins fournisseurs peuvent utiliser des clés d’environnement comme valeurs par défaut de tout le déploiement :
| Variable | Fournisseur |
|---|---|
OPENAI_API_KEY | OpenAI et OpenAI TTS |
ANTHROPIC_API_KEY | Anthropic |
GROQ_API_KEY | Groq |
GEMINI_API_KEY | Google Gemini |
MISTRAL_API_KEY | Mistral |
OPENROUTER_API_KEY | OpenRouter |
KIMI_API_KEY | Kimi Code de Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | API Hugging Face lorsqu’elles sont configurées |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | Déploiements ComfyUI exigeant une clé d’API |
Les utilisateurs peuvent aussi stocker les identifiants des fournisseurs dans l’interface lorsque des clés propres à chacun sont préférables. Les clés d’environnement ne sont utilisées qu’avec la projection de routage et d’authentification d’une définition intégrée non masquée. Les définitions importées, les définitions accessibles en écriture qui réutilisent un identifiant intégré et les routes personnalisées enregistrées par un administrateur exigent un identifiant stocké par ce compte. Libre WebUI ne joint aucune clé d’environnement à ces routes et ne l’expose pas lors des contrôles de découverte et de disponibilité. La confiance provient d’un hachage compilé de chaque manifeste livré ; les agencements de conteneurs où les anciens répertoires de plugins et les répertoires intégrés partagent un chemin restent donc pris en charge sans considérer un manifeste modifié comme intégré.
Les clés enregistrées par l’utilisateur sont liées à la définition effective du fournisseur, à sa source, à son contrat d’authentification et aux valeurs de routage. Les utilisateurs doivent réenregistrer leur clé après qu’un administrateur a modifié cette destination. Les anciennes clés non liées sont acceptées et liées lors de leur première utilisation uniquement pour une définition livrée exacte utilisant sa route intégrée.
Pour les lancements depuis les sources, les valeurs relatives PLUGINS_DIR sont résolues depuis le répertoire du serveur dorsal. Le lanceur empaqueté convertit au contraire une valeur relative explicitement configurée en chemin absolu depuis l’appelant avant le démarrage du serveur. Par compatibilité, Libre lit aussi le répertoire déterministe backend/plugins et les anciens emplacements sélectionnés par les configurations précédentes. Déplacez ces définitions dans $DATA_DIR/plugins ; la restauration signale les anciens chemins comme état externe et bloque une capture limitée aux volumes tant que des définitions personnalisées y restent. Les répertoires de plugins et les définitions JSON doivent être des entrées physiques ordinaires : Libre ne suit pas les liens symboliques de plugins.
Interface
| Variable | Valeur par défaut | Rôle |
|---|---|---|
VITE_API_BASE_URL | proxy de développement de même origine ou API de production | URL de base de l’API de l’interface |
VITE_WS_BASE_URL | déduite de l’URL de l’API | Base ws:/wss: absolue des sockets Chat et Work |
VITE_APP_VERSION | version du paquet injectée par Vite | Version affichée de l’application |
VITE_DEMO_MODE | false | Active les simulations du mode démo avec true |
VITE_API_TIMEOUT | 300000 | Délai de l’API de l’interface en millisecondes |
VITE_BACKEND_URL | http://localhost:3001 | Utilisée par certains composants auxiliaires d’authentification |
VITE_DEBUG_VERBOSE | non défini | Active les journaux de débogage détaillés de l’interface en développement |
VITE_LOG_LEVEL | non défini | Remplace le niveau de journalisation de l’interface |
ELECTRON_BUILD | non défini | Active le comportement Vite propre à Electron avec true |
VITE_WS_BASE_URL remplace tous les mécanismes de repli WebSocket pour Chat et le terminal Work. Elle peut comporter un préfixe de chemin de proxy inverse, mais doit être une URL ws: ou wss: absolue, sans identifiants, requête ni fragment. Lorsqu’elle n’est pas définie, les clients Electron file: utilisent ws://localhost:3001 ; les clients de navigateur déduisent leur base de VITE_API_BASE_URL, puis de l’origine du navigateur. Vite redirige l’origine de développement vers le serveur dorsal sur le port 3001.
Scripts de maintenance
| Variable | Rôle |
|---|---|
CHANGELOG_AI | Définir 0 pour désactiver les brouillons de journal assistés par l’IA |
CHANGELOG_AI_MODEL | Modèle Ollama utilisé pour générer les versions/journaux |
CHANGELOG_AI_TIMEOUT_MS | Délai de génération du journal par l’IA, en millisecondes |
Exemple :
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Exemple pour la production
NODE_ENV=production
PORT=3001
SERVE_FRONTEND=true
DATA_DIR=/data/libre-webui
CORS_ORIGIN=https://librewebui.example
BASE_URL=https://librewebui.example
JWT_SECRET=replace-with-a-long-random-secret
ENCRYPTION_KEY=replace-with-64-hex-characters
ENABLE_SIGNUP=false
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_TIMEOUT=300000
OLLAMA_LONG_OPERATION_TIMEOUT=900000
OLLAMA_MAX_CONTEXT=32768
TURNSTILE_SITE_KEY=...
TURNSTILE_SECRET_KEY=...
TURNSTILE_EXPECTED_HOSTNAME=librewebui.example