Variabile de mediu importante în Open WebUI (referință) în Open WebUI & RAG Local

docker run ... -e NUME=valoare ... ghcr.io/open-webui/open-webui:main

Variabilele se dau cu -e la docker run, în blocul environment: din Compose, într-un fișier --env-file sau în mediul procesului open-webui serve. Lista completă, cu sute de variabile grupate pe funcții, este pe docs.openwebui.com/reference/env-configuration. Tabelul de mai jos conține variabilele folosite cel mai des, cu valorile implicite din documentație, verificate în codul v0.12.4.

Variabilele marcate în documentație ca ConfigVar se comportă diferit: la prima pornire valoarea lor este scrisă în baza de date, iar la pornirile următoare Open WebUI folosește valoarea salvată, nu pe cea din mediu. Ele se schimbă din Settings > Admin. Cu ENABLE_PERSISTENT_CONFIG=False, variabilele de mediu au mereu prioritate, dar modificările făcute în interfață se pierd la repornire. Variabilele obișnuite (de exemplu WEBUI_SECRET_KEY, PORT, DATA_DIR) se citesc la fiecare pornire.

Câteva nume s-au schimbat: OLLAMA_API_BASE_URL este depreciat în favoarea OLLAMA_BASE_URL, ENABLE_API_KEY a devenit ENABLE_API_KEYS, iar WEBUI_JWT_SECRET_KEY este numele vechi al WEBUI_SECRET_KEY. O instalare standard face singură trei cereri externe: verificarea versiunii pe GitHub (ENABLE_VERSION_UPDATE_CHECK=false o oprește), lista de modele a conexiunii OpenAI implicite (ENABLE_OPENAI_API=false) și verificarea modelului local de embeddings pe Hugging Face (RAG_EMBEDDING_MODEL_AUTO_UPDATE=false). OFFLINE_MODE=true le blochează pe cele către Hugging Face și verificarea versiunii.

Concepte cheie și caracteristici

Concept / Parametru	Descriere practică
WEBUI_SECRET_KEY	Semnează sesiunile (JWT) și criptează date sensibile, de exemplu tokenurile OAuth ale uneltelor MCP. Dacă lipsește, start.sh generează una în fișierul .webui_secret_key din container, care se pierde la recreare. Documentația recomandă o valoare fixă (openssl rand -hex 32).
WEBUI_URL	Adresa publică a instalării; necesară pentru OAuth/SSO și pentru unele motoare de căutare. ConfigVar, implicit gol.
PORT / DATA_DIR	Portul (implicit 8080; la open-webui serve se folosește --port) și directorul de date (implicit ./data, în Docker /app/backend/data).
DATABASE_URL	Implicit sqlite:///${DATA_DIR}/webui.db; acceptă și PostgreSQL. Schimbarea adresei nu migrează datele.
WEBUI_AUTH	Implicit True. False dezactivează autentificarea, doar pe o instalare nouă, fără utilizatori.
ENABLE_SIGNUP / DEFAULT_USER_ROLE	Înregistrarea conturilor (implicit True) și rolul conturilor noi (implicit pending; opțiuni user, admin). Ambele ConfigVar.
OLLAMA_BASE_URL / OLLAMA_BASE_URLS	Serverul Ollama (implicit http://localhost:11434, în Docker http://host.docker.internal:11434), respectiv mai multe servere separate prin ;.
OPENAI_API_BASE_URL / OPENAI_API_KEY	Conexiunea OpenAI (implicit https://api.openai.com/v1); variantele OPENAI_API_BASE_URLS și OPENAI_API_KEYS primesc liste separate prin ;. ConfigVar.
ENABLE_OLLAMA_API / ENABLE_OPENAI_API	Activează sau ascund cele două tipuri de conexiuni; ambele implicit True.
DEFAULT_MODELS	Modelele preselectate într-un chat nou (ID-uri separate prin virgulă).
ENABLE_WEB_SEARCH / WEB_SEARCH_ENGINE / WEB_SEARCH_RESULT_COUNT	Căutarea web (implicit oprită), motorul (de ex. searxng, brave, tavily) și numărul de rezultate (implicit 3).
RAG_EMBEDDING_ENGINE / RAG_EMBEDDING_MODEL	Motorul de embeddings (gol = SentenceTransformers local; ollama, openai, azure_openai) și modelul (implicit sentence-transformers/all-MiniLM-L6-v2).
CHUNK_SIZE / CHUNK_OVERLAP / RAG_TOP_K	Fragmentarea documentelor: 1000 / 100 caractere și 3 fragmente pe căutare.
ENABLE_RAG_HYBRID_SEARCH / RAG_RERANKING_MODEL / RAG_TOP_K_RERANKER	Căutarea hibridă (implicit oprită), modelul de reranking (implicit gol) și câte fragmente păstrează rerankerul (implicit 3).
VECTOR_DB	Baza vectorială: implicit chroma (pgvector pe imaginea :slim); opțiuni între care qdrant, milvus, opensearch, elasticsearch, pinecone, weaviate.
CONTENT_EXTRACTION_ENGINE	Extragerea textului din documente: gol (intern), tika, docling, mistral_ocr, document_intelligence, datalab_marker, mineru, paddleocr_vl, external.
ENABLE_IMAGE_GENERATION / IMAGE_GENERATION_ENGINE	Generarea de imagini (implicit oprită) și motorul (implicit openai; comfyui, automatic1111, gemini).
AUDIO_STT_ENGINE / WHISPER_MODEL / AUDIO_TTS_ENGINE	Transcrierea (gol = Whisper local, modelul implicit base) și sinteza vocală (gol = fără TTS pe server, citește browserul).
ENABLE_API_KEYS	Permite crearea cheilor API; implicit False.
ENABLE_TOOLS / ENABLE_TOOL_SERVERS / ENABLE_DIRECT_INTEGRATIONS	Workspace Tools (implicit activ), serverele externe OpenAPI/MCP (implicit activ) și serverele de unelte adăugate de utilizatori (implicit oprit).
ENABLE_PERSISTENT_CONFIG	Implicit True: valorile salvate în interfață au prioritate față de mediu.
OFFLINE_MODE	Implicit False. True oprește verificarea versiunii și descărcările de modele de pe Hugging Face.

Exemple practice și scenarii reale

Exemplul 1: Variabile într-un fișier .env pentru Compose

Compose citește automat .env din același director pentru substituiri, iar env_file trece variabilele în container. Fișierul nu se publică în Git, pentru că are cheia secretă.

# .env
WEBUI_SECRET_KEY=inlocuieste-cu-rezultatul-openssl-rand-hex-32
OLLAMA_BASE_URL=http://ollama:11434
DEFAULT_USER_ROLE=pending
ENABLE_WEB_SEARCH=true
WEB_SEARCH_ENGINE=searxng
SEARXNG_QUERY_URL=http://searxng:8080/search

# docker-compose.yml (fragment)
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    env_file: .env

Exemplul 2: O variabilă ConfigVar care „nu are efect”

ENABLE_SIGNUP a fost salvată în baza de date la prima pornire. Schimbi valoarea din Settings > Admin > Authentication sau pornești o dată cu ENABLE_PERSISTENT_CONFIG=False. Ultima variantă din documentație, pentru cazul în care nu mai ai acces la interfață, este modificarea directă a tabelului config.

docker exec -it open-webui sqlite3 /app/backend/data/webui.db \
  "UPDATE config SET value = json('true') WHERE key = 'ui.enable_signup';"

Exemplul 3: Instalare fără cereri externe automate

Documentația avertizează că, fără un model de embeddings descărcat înainte, cu OFFLINE_MODE prima încărcare de document eșuează cu „No embedding model is loaded”.

docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  -e WEBUI_SECRET_KEY=cheia-ta \
  -e OFFLINE_MODE=true \
  -e ENABLE_OPENAI_API=false \
  --name open-webui --restart always \
  ghcr.io/open-webui/open-webui:main

Greșeli frecvente și capcane

• Schimbi o variabilă ConfigVar în docker-compose.yml și te aștepți să se aplice după repornire. Valoarea salvată în baza de date are prioritate; folosește interfața sau ENABLE_PERSISTENT_CONFIG=False.
• Pornești cu ENABLE_PERSISTENT_CONFIG=False și modifici setări în interfață: par aplicate, dar se pierd la repornire.
• Lași WEBUI_SECRET_KEY nesetat: la recrearea containerului se generează altă cheie, toți utilizatorii sunt deconectați, iar tokenurile OAuth ale uneltelor MCP și secretele MFA nu mai pot fi decriptate.

Noțiuni și module înrudite

• docker-run-open-webui
• docker-compose-ollama-webui
• conectare-ollama-api
• rag-chunking-settings