Variabili d’ambiente
Questa pagina elenca le variabili per operatori lette da backend, frontend e script di manutenzione attuali. I canary interni per test sono omessi.
Server backend
| Variabile | Predefinito | Scopo |
|---|---|---|
NODE_ENV | development | Modalità runtime |
PORT | 3001 sviluppo, 8080 produzione | Porta HTTP |
TRUST_PROXY | non impostato (0 Helm) | Numero esatto di hop proxy fidati per derivare l'indirizzo client |
CORS_ORIGIN | origini locali | Origini browser esatte, separate da virgola; * consente qualsiasi origine valida |
SERVE_FRONTEND | non impostato | Servire frontend compilato quando true |
DOCKER_ENV | non impostato | Comportamento Docker quando true |
DATA_DIR | backend/data; ~/.libre-webui nel CLI | Directory dati persistenti |
PLATFORM_PREFLIGHT_TMP_DIR | backend/temp/preflight; cache utente nel CLI | Spazio temporaneo per copia privata DB/WAL; dimensiona per entrambi |
PLUGIN_UPLOAD_TEMP_DIR | libre-webui-plugin-uploads nella temp OS | Spazio upload in corso |
PLUGINS_DIR | $DATA_DIR/plugins | Directory scrivibile dei plugin |
BASE_URL | http://localhost:3001 | Base callback OAuth |
LOG_LEVEL | info (warn nei test) | Livello log |
LOG_FORMAT | text | json abilita log strutturati con timestamp, ID e redazione |
OTEL_EXPORTER_OTLP_ENDPOINT | non impostato | Export OTLP/HTTP JSON opt-in; assente significa nessuna telemetria |
OTEL_EXPORTER_OTLP_HEADERS | non impostato | Header key=value separati da virgola |
OTEL_SERVICE_NAME | libre-webui | Attributo service.name |
WEBUI_HOST | loopback; 0.0.0.0 Docker | Indirizzo di ascolto |
OPEN_BROWSER | true servendo frontend | false non apre browser |
FULL_DOCUMENT_CONTEXT_MAX_TOKENS | 32000 | Limite token modalità documento completo (1000-2000000) |
GALLERY_RETENTION_DAYS | non impostato (per sempre) | Elimina media più vecchi |
RECOVERY_DRILL_INTERVAL_HOURS | non impostato (drill disattivati) | Drill verificato ogni N ore (solo) |
RECOVERY_DRILL_HISTORY | 60 | Voci cronologia |
Le voci di CORS_ORIGIN corrispondono alle origini browser serializzate:
schema, hostname e porta facoltativa, senza percorso, credenziali, query o
frammento. Le richieste devono avere un'unica origine canonica; valori
malformati ed elenchi di origini vengono rifiutati anche con CORS_ORIGIN=*. I
client che omettono Origin restano consentiti. L'origine opaca null richiede
una voce null esplicita oppure *.
In Docker (DOCKER_ENV=true) e nelle modalità non di produzione vengono
accettati anche, per le origini HTTP(S), localhost esatto e gli indirizzi IPv4
letterali in 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 e
100.64.0.0/10. Gli hostname che iniziano soltanto con quelle stringhe, come
localhost.attacker.example, non sono indirizzi locali. Le origini IPv6
richiedono una voce esplicita oppure *; non sono incluse automaticamente
nell'eccezione di rete. I deployment nativi di produzione usano solo l'elenco
esplicito di origini o il carattere jolly. CORS non sostituisce
l'autenticazione dell'API tramite bearer token.
Le esecuzioni da sorgente ancorano valori relativi DATA_DIR, PLUGINS_DIR, PLATFORM_PREFLIGHT_TMP_DIR alla directory backend. DATA_DIR=./data sceglie backend/data; il legacy DATA_DIR=./backend/data sceglie backend/backend/data. Cambialo solo in una migrazione fermata e con backup. Senza valore, usa la directory storica se è l'unico store. Se entrambe contengono stato e nessuna è selezionata, l'avvio fallisce invece di indovinare, copiare o unire.
npx, npm globale e Homebrew conservano in ~/.libre-webui. Un DATA_DIR relativo esplicito viene risolto dalla directory chiamante e convertito in assoluto. PLUGINS_DIR segue la stessa regola; assente rimane in $DATA_DIR/plugins. Il preflight usa cache esterna: ~/Library/Caches/libre-webui su macOS, %LOCALAPPDATA%\libre-webui Windows o ${XDG_CACHE_HOME:-~/.cache}/libre-webui. Homebrew usa var/libre-webui/preflight. Imposta PLATFORM_PREFLIGHT_TMP_DIR se non contiene database e WAL. Docker/Helm usano /app/backend/data e /app/backend/temp/preflight su mount separati.
Fondazione della piattaforma
solo usa SQLite, blob e vettori locali cifrati, coordinamento locale e worker integrato. team usa PostgreSQL, S3 privato, PGVector, Redis e worker esterno. Team fallisce chiuso se le dipendenze condivise non sono selezionate insieme.
| Variabile | Predefinito | Scopo |
|---|---|---|
LIBRE_PLATFORM_MODE | solo | Profilo solo o team |
DATABASE_BACKEND | sqlite | sqlite o postgres |
DATABASE_URL | non impostato | URL PostgreSQL richiesta con postgres |
DATABASE_SSL_MODE | verify-full | TLS disable, require, verify-full |
POSTGRES_MIGRATION_MODE | apply | Migrazioni sotto leader lock o validate |
POSTGRES_POOL_MAX | 10 | Connessioni per processo (1-100) |
POSTGRES_CONNECT_TIMEOUT_MS | 5000 | Timeout connessione (1-60000 ms) |
POSTGRES_IDLE_TIMEOUT_MS | 30000 | Timeout inattivo (1-600000 ms) |
POSTGRES_STATEMENT_TIMEOUT_MS | 30000 | Timeout statement (1-600000 ms) |
POSTGRES_MIGRATION_LOCK_TIMEOUT_MS | 60000 | Attesa lock (1-600000 ms) |
BLOB_STORE_BACKEND | local | local cifrato o s3 privato |
VECTOR_STORE_BACKEND | embedded con SQLite | embedded cifrato o pgvector |
COORDINATION_BACKEND | local solo; redis team | Coordinamento locale o Redis |
REDIS_URL | non impostato | URL redis:/rediss: richiesta |
REDIS_KEY_PREFIX | libre | Namespace 1-64 caratteri |
REDIS_CONNECT_TIMEOUT_MS | 5000 | Timeout iniziale, max 60 secondi |
JOB_WORKER_MODE | embedded solo; external team | Handler nell'app o worker condiviso |
RESOURCE_LEASE_TTL_MS | 30000 | TTL lease (5000-300000) |
JOB_WORKER_CONCURRENCY | 4 | Lavori simultanei (1-32) |
CHAT_STREAM_EVENT_RETENTION_HOURS | 24 | Ore retention chunk chat |
PLATFORM_EVENT_RETENTION_DAYS | 30 | Giorni retention eventi |
PLATFORM_JOB_RETENTION_DAYS | 30 | Giorni retention lavori |
LIBRE_SKIP_STARTUP_INTEGRITY_SCAN | non impostato | 1 salta la scansione profonda successiva |
STORAGE_ENCRYPTION_KEYS | non impostato | Mappa JSON con legacy uguale a ENCRYPTION_KEY |
STORAGE_ENCRYPTION_ACTIVE_KEY_ID | non impostato | ID per nuove scritture |
BLOB_QUOTA_BYTES_PER_USER | 10737418240 | Byte plaintext massimi per proprietario |
BLOB_QUOTA_RESERVATION_TTL_MS | 3600000 | Vita prenotazione abbandonata (min 60000 ms) |
S3_BUCKET | non impostato | Bucket richiesto con s3 |
S3_REGION | non impostato | Regione richiesta |
S3_ENDPOINT | default provider | Endpoint HTTP(S) opzionale |
S3_ACCESS_KEY_ID | catena credenziali SDK | Chiave esplicita |
S3_SECRET_ACCESS_KEY | catena credenziali SDK | Richiesta con chiave esplicita |
S3_SESSION_TOKEN | non impostato | Token opzionale |
S3_FORCE_PATH_STYLE | false | true per path-style |
S3_BLOB_PREFIX | libre/blobs | Prefisso opaco |
Senza mappa versionata, gli adattatori usano ENCRYPTION_KEY come ID legacy; senza, leggono ${DATA_DIR}/.encryption_key senza generare/modificare. Configurazione e file devono coincidere. Introducendo una mappa, mantieni la chiave sotto legacy finché oggetti e vettori non sono riscritti/verificati. Conflitti, permessi insicuri, symlink o chiavi mancanti falliscono chiuso.
Redis coordina, non è persistenza canonica. Da solo non rende SQLite/file sicuri tra repliche. In team, rate limit HTTP, connessioni, STT/TTS/audio, import e terminali Work usano admission condivisa. Errori restituiscono 503 o abortiscono, senza fallback locale. Vedi Fondazione piattaforma.
Compose/Helm team inoltrano selettori e tuning ad app e worker. Nel chart i non-secret sono in env; connessioni/chiavi in secrets.redisUrl, secrets.databaseUrl, secrets.storageEncryptionKeys. I pool sono per processo: riserva (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX più margine. Mantieni DATABASE_SSL_MODE=verify-full remoto; Compose isolato usa disable. Team Helm richiede secrets.jwtSecret stabile in ogni Pod. S3 riceve chiavi opache e ciphertext.
Gli archivi integrati conservano pool/timeout PostgreSQL, Redis, quote blob, selettori e S3 nella configurazione cifrata e firmata.
App e worker ricevono stessi OLLAMA_BASE_URL, OLLAMA_TIMEOUT, OLLAMA_LONG_OPERATION_TIMEOUT, OLLAMA_MAX_CONTEXT. I valori devono essere interi decimali positivi completi. 300000ms, esponente/esadecimale, fuori range o timeout lungo inferiore falliscono l'avvio.
Helm limita TRUST_PROXY a 0–16 e lo invia solo ai Pod HTTP. Usa 0 diretto e numero esatto nella catena; mai true.
La compatibilità PostgreSQL è esatta. App/worker usano Recreate; drena tutti i vecchi Pod prima dell'upgrade e lascia un nuovo processo migrare sotto advisory lock. Niente versioni miste o zero-downtime. Rollback ripristina l'archivio verificato in target puliti.
Un'app team attiva richiede worker.replicaCount >= 1. Azzera app e worker per sospensione completa; app zero e worker positivo è drain/recupero worker-only.
Helper di backup privato
Queste variabili configurano deploy/private/libre-webui-backup e sono lette dallo script di manutenzione:
| Variabile | Predefinito | Scopo |
|---|---|---|
LIBRE_WEBUI_STACK_DIR | /opt/libre-webui | Directory Compose privata |
LIBRE_WEBUI_BACKUP_DIR | /var/backups/libre-webui | Directory protetta backup/lock |
LIBRE_WEBUI_BACKUP_RETENTION_DAYS | 14 | Età di rimozione |
LIBRE_WEBUI_CONTAINER_NAME | libre-webui | Container da ispezionare |
LIBRE_WEBUI_BACKUP_KEY_DIR | /etc/libre-webui/backup-keys | Directory chiavi cifratura/firma |
LIBRE_WEBUI_RESTORE_IMAGE | richiesta per restore | ID/digest immutabile revisionato |
LIBRE_WEBUI_RESTORE_CONFIG_DIR | percorso per volume in /etc/libre-webui/restored | Nuova directory configurazione recuperata |
L'unità systemd legge override da /etc/libre-webui/backup.env root-owned, modalità 0600. La sandbox permette scrittura solo nella directory predefinita. Un LIBRE_WEBUI_BACKUP_DIR custom richiede anche la directory esatta precreata in un drop-in ReadWritePaths=; vedi Distribuzione remota privata.
Autenticazione e sicurezza
| Variabile | Predefinito | Scopo |
|---|---|---|
ENABLE_SIGNUP | false | Registrazioni dopo il primo admin |
JWT_SECRET | generato/fallback sviluppo | Segreto firma; impostalo in produzione |
JWT_EXPIRES_IN | 7d | Durata sessione |
ENCRYPTION_KEY | auto-generata | Chiave esadecimale 64 caratteri |
DEBUG_ENCRYPTION | non impostato | Log debug cifratura |
TURNSTILE_SITE_KEY | non impostato | Chiave sito Turnstile |
TURNSTILE_SECRET_KEY | non impostato | Chiave segreta |
TURNSTILE_EXPECTED_HOSTNAME | hostname da BASE_URL | Host richiesto |
MFA_REQUIRED_MODE | non impostato (toggle admin, optional) | optional o required |
WEBAUTHN_RP_ID | hostname richiesta | Relying-party ID fisso |
VAPID_PUBLIC_KEY | generata e cifrata | Chiave pubblica VAPID (base64url P-256 point) |
VAPID_PRIVATE_KEY | generata e cifrata | Chiave privata VAPID (base64url scalar) |
VAPID_SUBJECT | mailto:admin@localhost | Contatto Web Push |
Turnstile è attivo solo con entrambe.
ENABLE_SIGNUP=false consente comunque il primo admin in database vuoto. Proteggi una route remota di bootstrap con una frontiera identità esterna.
Ogni JWT è legato a sessione server-side (claim sid); logout/revoca invalida subito su tutte le repliche e chiude WebSocket.
| Variabile | Predefinito | Scopo |
|---|---|---|
AUDIT_RETENTION_DAYS | 180 | Giorni retention audit |
Single Sign-On OIDC generico
Qualunque provider OpenID Connect con discovery document può essere usato. Il flusso usa PKCE (S256), stato CSRF e nonce nel token verificato. Identità legate a claim sub.
| Variabile | Predefinito | Scopo |
|---|---|---|
OIDC_ISSUER_URL | non impostato | Base issuer; discovery da <issuer>/.well-known/openid-configuration |
OIDC_CLIENT_ID | non impostato | Client ID |
OIDC_CLIENT_SECRET | non impostato | Client secret |
OIDC_DISPLAY_NAME | Single Sign-On | Etichetta login |
OIDC_SCOPES | openid profile email | Scope |
OIDC_CALLBACK_URL | BASE_URL + route OIDC | Redirect URI |
OIDC_ALLOWED_EMAIL_DOMAINS | non impostato | Domini email verificati |
OIDC_GROUP_CLAIM | groups | Claim gruppi |
OIDC_ADMIN_GROUPS | non impostato | Gruppi che controllano admin |
OIDC_SYNC_GROUPS | false | true sincronizza gruppi |
Richiede issuer, ID e secret. Email già usata da account locale non collegato viene rifiutata; la creazione rispetta ENABLE_SIGNUP.
Admisson WebSocket:
| Variabile | Predefinito | Scopo |
|---|---|---|
CHAT_WS_MAX_PAYLOAD_BYTES | 10 MiB | Payload massimo |
CHAT_WS_MAX_MESSAGES_PER_MINUTE | 120 | Messaggi per connessione |
CHAT_WS_MAX_ACTIVE_GENERATIONS_PER_USER | 4 | Generazioni per account |
CHAT_WS_MAX_CONNECTIONS_PER_USER | 5 | Socket simultanei |
WEBSOCKET_TICKET_TTL_MS | 30000 | Vita ticket, max 60s |
Il browser scambia Authorization con ticket opaco breve, monouso e hashato. Quando CORS_ORIGIN o BASE_URL è configurato, Origin deve coincidere. Impostane almeno uno in remoto; senza, è permissivo per sviluppo. Upgrade senza Origin restano per Electron/non-browser, ma richiedono ticket e stessi controlli; limita con TLS/firewall/proxy.
OAuth
| Variabile | Scopo |
|---|---|
GITHUB_CLIENT_ID | GitHub client ID |
GITHUB_CLIENT_SECRET | GitHub secret |
GITHUB_CALLBACK_URL | Callback override |
HUGGINGFACE_CLIENT_ID | Hugging Face client ID |
HUGGINGFACE_CLIENT_SECRET | Hugging Face secret |
HUGGINGFACE_CALLBACK_URL | Callback override |
Senza callback, Libre li crea da BASE_URL.
Ollama
| Variabile | Predefinito | Scopo |
|---|---|---|
OLLAMA_BASE_URL | http://localhost:11434 | URL base |
DEFAULT_MODEL | (vuoto) | Modello con cui iniziano i nuovi account finché non ne scelgono uno (--model da CLI) |
OLLAMA_TIMEOUT | 300000 | Timeout standard (1.000-3.600.000 ms) |
OLLAMA_LONG_OPERATION_TIMEOUT | 900000 | Timeout lungo non inferiore a OLLAMA_TIMEOUT |
OLLAMA_MAX_CONTEXT | 32768 | Contesto massimo (128-2.097.152 token) |
Ricerca web
| Variabile | Predefinito | Scopo |
|---|---|---|
SEARXNG_URL | non impostato | Endpoint predefinito; l'admin lo abilita nelle Impostazioni |
Notifiche email
Queste variabili configurano il server di posta in uscita che gli amministratori gestiscono in Impostazioni > Gestione utenti > Accesso e criteri > Notifiche email. Un valore salvato lì ha la precedenza sulla variabile; svuotare il campo nella UI ripristina la variabile. Le email restano disattivate finché un amministratore non attiva l'interruttore, e ogni utente sceglie comunque se attivarle per ciascun tipo di notifica in Impostazioni > Notifiche.
| Variabile | Predefinito | Scopo |
|---|---|---|
SMTP_HOST | non impostato | Nome host del server di posta |
SMTP_PORT | 587, oppure 465 con tls | Porta del server di posta |
SMTP_SECURITY | starttls | starttls (eleva una connessione in chiaro), tls (TLS implicito) o none (rete affidabile) |
SMTP_USER | non impostato | Utente per l'autenticazione; lascia non impostato per un relay che accetta posta senza autenticazione |
SMTP_PASSWORD | non impostato | Password per l'autenticazione; una password salvata nella UI viene cifrata e ha la precedenza |
SMTP_FROM | non impostato | Mittente, ad esempio Libre WebUI <[email protected]> |
SMTP_TLS_REJECT_UNAUTHORIZED | true | Imposta false solo per un relay con certificato autofirmato |
BASE_URL | non impostato | URL pubblico dell'istanza, usato per i link nei messaggi |
Motore Strands
| Variabile | Predefinito | Scopo |
|---|---|---|
LIBRE_STRANDS_ACCESS | non impostata (impostazione admin, disattivo) | Fissa chi può usare il motore Strands integrato: disabled, admins o all-users. Qualsiasi altro valore lo blocca su disattivato |
Runtime Work
Queste variabili configurano Work sulla macchina o cluster del backend. Docker è default; Helm sceglie Kubernetes con work.enabled=true.
| Variabile | Predefinito | Scopo |
|---|---|---|
WORK_RUNTIME_IMAGE | node:22.22-bookworm@sha256:2d178f2785b96dfbf62a416ca2e40f50e30150b4ff3320d706f0d96e90600eb3 | Immagine sandbox fissata |
WORK_DOCKER_COMMAND | docker | Eseguibile CLI |
WORK_COMMAND_TIMEOUT_MS | 120000 | Timeout default; tool fino a 600000 ms |
WORK_MAX_OUTPUT_CHARS | 50000 | Limite stdout/stderr per stream |
WORK_MAX_AGENT_ROUNDS | 48 | Round per esecuzione |
WORK_STATUS_BLURB_MODEL | 1 | 0 salta la richiesta di stato agente |
WORK_MEMORY_LIMIT | 2g | Memoria per container |
WORK_CPU_LIMIT | 2 | CPU |
WORK_PIDS_LIMIT | 256 | Processi |
WORK_PREVIEW_PORT | 4173 | Porta preview interna |
WORK_PREVIEW_BIND | 127.0.0.1 | Interfaccia host; con Compose su Docker Engine nativo serve un'interfaccia bridge non pubblica raggiungibile |
WORK_DOCKER_PUBLISHED_HOST | app: uguale a WORK_PREVIEW_BIND; Compose: host.docker.internal | Host/IP backend per preview/schermo/audio |
WORK_COMPUTER_SCREEN_PORT | 6080 | Porta bridge schermo |
WORK_COMPUTER_AUDIO_PORT | 6081 | Porta bridge audio |
WORK_MAX_ACTIVE_RUNTIMES_GLOBAL | 3 | Attività runtime simultanee istanza |
WORK_MAX_ACTIVE_RUNTIMES_PER_USER | 2 | Per utente |
WORK_MAX_TASKS_GLOBAL | 500 | Attività persistenti istanza |
WORK_MAX_TASKS_PER_USER | 100 | Per admin |
WORK_NETWORK_NAME | libre-webui-work | Bridge gestito |
WORK_RUN_LEASE_WAIT_MS | 60000 | Attesa lease condiviso (team) |
WORK_RUNTIME_DNS | non impostato | IP resolver separati da virgola |
WORK_DOCKER_SOCKET | DOCKER_HOST se unix:// o tcp://, altrimenti /var/run/docker.sock | Endpoint Engine |
WORK_TERMINAL_MAX_SESSIONS_PER_TASK | 2 | Terminali simultanei |
WORK_TERMINAL_IDLE_TIMEOUT_MS | 900000 | Timeout inattività |
WORK_RUNTIME_IDLE_TIMEOUT_MS | 1800000 (30 min) | Ferma sandbox inattivo |
WORK_HOST_WORKSPACES_ENABLED | false | Permetti cartella host |
WORK_HOST_WORKSPACE_ROOTS | home utente server | Radici : |
WORK_RUNTIME_BACKEND | docker | docker/kubernetes |
WORK_K8S_NAMESPACE | libre-webui-work | Namespace |
WORK_K8S_STORAGE_CLASS | default cluster | StorageClass |
WORK_K8S_WORKSPACE_SIZE | 5Gi | PVC per attività |
WORK_K8S_POD_READY_TIMEOUT_MS | 900000 | Attesa Running |
WORK_K8S_POD_GONE_TIMEOUT_MS | 60000 | Attesa eliminazione |
AGENT_CLI_MODELS_ENABLED | non impostato (toggle admin, off) | Fissa lo stato dei modelli di agenti CLI diretti; se non impostata, usa il relativo interruttore separato |
TOOLS_ACCESS_MODE | non impostato (admin-only) | admins/all-users |
STT_ACCESS_MODE | non impostato (tutti) | Accesso STT |
TTS_ACCESS_MODE | non impostato (tutti) | Accesso TTS |
VOICE_MODE_ACCESS_MODE | non impostato (tutti) | Modalità voce |
VOICE_CLONING_ACCESS_MODE | non impostato (tutti) | Clonazione |
TOOLS_PRIVATE_NETWORK_ALLOWLIST | non impostato | Host esatti privati |
AGENT_CLI_TIMEOUT_MS | 600000 | Timeout agent CLI |
CODEX_OAUTH_MODELS_ENABLED | true | Codex (ChatGPT) agli admin |
CODEX_HOME | ~/.codex | Percorso auth.json |
Agent CLI e credenziali Codex sono node-local e supportati solo in solo. Team richiede AGENT_CLI_MODELS_ENABLED=false e CODEX_OAUTH_MODELS_ENABLED=false; usa Ollama o plugin con stato condiviso.
Una cartella host viene montata in /workspace, permettendo accesso diretto. Kubernetes la rifiuta. Mantieni WORK_HOST_WORKSPACES_ENABLED off e WORK_HOST_WORKSPACE_ROOTS stretto. I percorsi risolvono symlink e rifiutano .ssh, .gnupg, .aws, .config.
I modelli Agent CLI espongono claude, codex installati senza API key. Solo admin li vedono e il CLI eredita credenziali: equivalente ad accesso shell degli agenti.
Le attività networked entrano nella bridge WORK_NETWORK_NAME senza comunicazione inter-container. WORK_RUNTIME_DNS usa resolver filtrante; valori non IP sono rifiutati. Non limita IP diretti, quindi serve firewall. Kubernetes usa work.networkPolicy.blockedEgressCidrs.
Terminale e diagnostica parlano Engine API via WORK_DOCKER_SOCKET, poi DOCKER_HOST (unix:// o tcp:// HTTP, vedi docker-compose.socket-proxy.yml), poi /var/run/docker.sock. ssh:// o tcp:// con DOCKER_TLS_VERIFY rendono terminale/diagnostica indisponibili, mentre il resto usa CLI. Kubernetes usa Pod exec.
La porta preview è interna e pubblicata dinamicamente su loopback. Fissa l'immagine. WORK_MAX_AGENT_ROUNDS vale per Ollama e plugin; budget tool max(128, WORK_MAX_AGENT_ROUNDS × 8). Esaurito, richiede handoff finale e termina needs_input; una nuova esecuzione continua. Output persistito circa 20.000 caratteri più marker.
Compose abilita Work con CLI e socket. Variabili:
| Variabile | Predefinito | Scopo |
|---|---|---|
DOCKER_GID | 0 | Gruppo socket aggiunto all'utente |
DOCKER_SOCKET | /var/run/docker.sock | Percorso socket |
DOCKER_GID deve essere il gruppo visto nel container; macOS differisce. Team non monta socket finché non aggiungi docker-compose.team.work.yml, che usa proxy filtrato per app/worker. Creare container resta controllo host; preferisci daemon dedicato/rootless. Helm usa Pod/PVC con work.enabled=true.
solo ha zero o una replica. team completo può averne molte grazie a PostgreSQL, S3, PGVector e Redis. I Pod Work scalano separatamente e il worker riceve stessa immagine, StorageClass e work.env.
Compose accetta WEBUI_BIND_ADDRESS default 127.0.0.1 e WEBUI_PORT default 8080; mantieni loopback salvo necessità affidabile.
Scoperta modelli provider
| Variabile | Predefinito | Scopo |
|---|---|---|
PLUGIN_MODEL_DISCOVERY_TTL_MS | 21600000 (6 h) | Età per refresh |
PLUGIN_MODEL_DISCOVERY_RETRY_MS | 600000 (10 min) | Intervallo minimo |
PLUGIN_MODEL_DISCOVERY_REFRESH_DEADLINE_MS | 3000 | Attesa prima della risposta |
Refresh tardivo appare dopo. Aggiorna modelli ignora intervallo.
Chiavi plugin provider
| Variabile | Provider |
|---|---|
OPENAI_API_KEY | OpenAI e OpenAI TTS |
ANTHROPIC_API_KEY | Anthropic |
GROQ_API_KEY | Groq |
GEMINI_API_KEY | Google Gemini |
MISTRAL_API_KEY | Mistral |
DEEPSEEK_API_KEY | DeepSeek |
AWS_BEARER_TOKEN_BEDROCK | Chiave API di Amazon Bedrock |
OPENROUTER_API_KEY | OpenRouter |
KIMI_API_KEY | Kimi Code di Moonshot AI |
GITHUB_API_KEY | GitHub Models |
HUGGINGFACE_API_KEY | API Hugging Face |
ELEVENLABS_API_KEY | ElevenLabs TTS |
COMFYUI_API_KEY | ComfyUI con chiave |
Gli utenti possono salvare credenziali. Le chiavi ambientali valgono solo per definizione inclusa non shadowed; importate, scrivibili con ID incluso e route custom richiedono credenziale account. La fiducia viene dall'hash compilato.
Le chiavi salvate dagli utenti sono legate alla definizione effettiva del provider, all’origine, al contratto di autenticazione e ai valori di routing. Gli aggiornamenti del catalogo dei modelli le conservano. Gli utenti devono salvare di nuovo la chiave dopo che un amministratore ha cambiato quella destinazione. Le chiavi non vincolate precedenti all’aggiornamento sono accettate e vincolate al primo utilizzo solo per una definizione distribuita esatta che usa la sua route inclusa.
PLUGINS_DIR relativo da source risolve dal backend, nel pacchetto dal chiamante. Libre legge anche backend/plugins e percorsi legacy; sposta in $DATA_DIR/plugins. Il recovery blocca snapshot solo-volume mentre esiste stato esterno. Plugin devono essere file fisici, niente symlink.
Frontend
| Variabile | Predefinito | Scopo |
|---|---|---|
VITE_API_BASE_URL | proxy di sviluppo stessa origine o API di produzione | URL base API |
VITE_WS_BASE_URL | inferito dall'API | Base ws:/wss: Chat/Work |
VITE_APP_VERSION | versione package | Versione mostrata |
VITE_DEMO_MODE | false | Mock quando true |
VITE_API_TIMEOUT | 300000 | Timeout ms |
VITE_BACKEND_URL | http://localhost:3001 | Helper auth |
VITE_DEBUG_VERBOSE | non impostato | Log debug |
VITE_LOG_LEVEL | non impostato | Livello log |
ELECTRON_BUILD | non impostato | Comportamento Electron con true |
VITE_WS_BASE_URL sostituisce fallback WebSocket; deve essere assoluto ws:/wss: senza credenziali, query o fragment. Assente, Electron file: usa ws://localhost:3001; il browser deriva dalla VITE_API_BASE_URL, poi dall'origine del browser. Vite instrada in proxy l'origine di sviluppo verso il backend sulla porta 3001.
Script di manutenzione
| Variabile | Scopo |
|---|---|
CHANGELOG_AI | 0 disabilita bozze IA |
CHANGELOG_AI_MODEL | Modello Ollama |
CHANGELOG_AI_TIMEOUT_MS | Timeout ms |
CHANGELOG_AI_MODEL=glm-5.2:cloud npm run changelog
CHANGELOG_AI=0 npm run release:minor
Esempio produzione
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