Open WebUI

Self-hosted chat interface for any LLM.

Overview

Open WebUI is a chat front end for large language models that you host yourself. It talks to any OpenAI-compatible API and to Ollama, and keeps the conversations, the uploaded documents and the accounts in its own database rather than in a vendor's. On top of plain chat it carries a document workspace with retrieval, a prompt and model library, per-user and per-group permissions, and an OpenAI-shaped API of its own.

This template runs upstream's official image unmodified. There is no overlay Dockerfile here and no code in this repository between you and the app.

What you get by hosting it

• Chat histories, uploaded files and accounts on a volume you own, not in a provider's account.
• One interface over several providers at once: add OpenAI, OpenRouter, Anthropic-compatible gateways and a remote Ollama side by side and switch models mid-conversation.
• Document retrieval that runs locally. The image bakes in the sentence-transformers/all-MiniLM-L6-v2 weights, so uploading a file and asking about it needs no embedding provider and no second key. (The boot still reaches huggingface.co to resolve that model's snapshot and fetch a few small auxiliary files beside the cached weights.)
• Accounts, groups and per-model permissions, so the instance can be shared without sharing the provider key.
• Speech-to-text locally as well: faster-whisper and the base model are baked into the image.

What you need before deploying

• An API key for whichever model provider you want to chat with, if you want the first chat to work straight away. OPENAI_API_KEY is optional and can be added in the app afterwards.
• Nothing else. The first account is created in the browser after deploy, not from a variable.

Configuration

There are no required variables. Open WebUI has no environment variable that seeds an admin account, and it does not need one: against an empty database the sign-in page opens in onboarding mode, the first account created is promoted to admin, and the server then sets ui.enable_signup to false itself, so the second visitor is refused. Create that account as soon as the deploy is healthy, because until you do, the URL hands admin to whoever reaches it first.

Fixed by the template: DATA_DIR=/data (puts webui.db, uploads/ and the Chroma vector store on the volume; the baked embedding, Whisper and tiktoken caches stay at their own absolute paths inside the image), WEBUI_URL (the service's own URL, used for the absolute links the app generates), CORS_ALLOW_ORIGIN (also the service's own URL, see below) and ENABLE_OLLAMA_API=False (no Ollama is deployed alongside this, and the image's default of /ollama would have the server retrying a host that is not there on every model list; turn it back on in Admin Settings > Connections to point at a reachable one).

CORS_ALLOW_ORIGIN is worth a paragraph because the image's default is looser than it looks. Unset, it is *, and the app registers its CORS middleware with allow_credentials=True, so the wildcard is not served as *: the requesting origin is echoed back instead, whatever it is. The template pins it to this instance's own origin, which is where the app serves its own frontend from, so nothing the UI does is affected. Unlike the settings below it is read from the environment at import time rather than being a PersistentConfig, and a value that is not a scheme plus a host raises before the server binds. It is fixed rather than a deploy-form field, so if you put the instance behind a custom domain, or need a second origin to call the API, edit the variable on the service afterwards (a semicolon separates origins) and restart.

WEBUI_SECRET_KEY is generated by the platform. Left unset, the app mints one into /app/backend/.webui_secret_key, which is on the container filesystem rather than the volume, so every restart would log everyone out.

Several of Open WebUI's settings are what upstream calls PersistentConfig: the environment variable seeds the database on first boot and the app's own admin pages own the value from then on. OPENAI_API_KEY, OPENAI_API_BASE_URL and ENABLE_OLLAMA_API are all of that kind. Changing one after the first boot has no effect; change it in Admin Settings instead.

The service listens on port 8080 and is health-checked on /health, the app's own unauthenticated readiness endpoint, which is also what upstream's container HEALTHCHECK probes.

It is declared alwaysOn: false. Chat, indexing and model listing are all driven by an inbound request, which is itself what wakes the machine. The cost is the cold start: the server imports torch and loads the embedding model before it serves anything, which took about 35 seconds from container start to a healthy /health on a fresh deploy. The one thing an idle machine would miss is Automations: Open WebUI runs a scheduler inside the process, and a scheduled automation cannot fire on a machine that has scaled to zero. Set alwaysOn: true if you create any.

After deploy

1. Open the service URL. With no accounts yet the page opens on the sign-up form.
2. Create the first account. It becomes the admin, and sign-up closes behind it.
3. If you did not set OPENAI_API_KEY, open the account menu > Admin Panel > Settings > Connections and add a provider: a base URL and a key for anything OpenAI-compatible, or an Ollama URL.
4. Pick a model at the top of a new chat and send a message.
5. To chat over your own documents, click + in the message box to upload a file, or load one into Workspace > Knowledge and reference it with #. Embedding runs locally with the model baked into the image, so this works with no second provider.

Links

• Architectures: linux/amd64 and linux/arm64. Upstream's v0.11.4 index carries both; nothing is rebuilt here.
• Upstream: https://github.com/open-webui/open-webui
• Documentation: https://docs.openwebui.com
• Image: ghcr.io/open-webui/open-webui, pinned to v0.11.4
• License: the Open WebUI License (upstream open-webui/open-webui), BSD-3-Clause plus a branding clause that applies above 50 end users. https://docs.openwebui.com/license

This template deploys with no required variables — one click and it runs.