Open WebUI

Chat interface for local and remote LLMs. One container, one .env line to decide which of three quite different stacks you get.

Quick start

cp .env.example .env
$EDITOR .env            # pick OWUI_TAG, point it at your models
docker compose up -d

Open http://<host>:3033. The first account created becomes the admin.

Choosing a tag

OWUI_TAG in .env is the whole configuration. Everything else is detail.

Tag	What's inside	Choose it when
`main` / `latest`	WebUI only	Models run somewhere else — the Docker host, another machine, a Mac, or a hosted API. The default, and the right answer most of the time.
`cuda`	+ CUDA runtime	You're on an NVIDIA host and use document RAG or voice input
`ollama`	+ Ollama bundled in	One machine, one container, models managed inside it
`dev`	main branch, unreleased	Testing only
`v0.11.0`	a frozen release	You want upgrades to be a decision, not a surprise

main and latest are the same rolling image — upstream says so explicitly. Version tags stay frozen.

What `cuda` actually accelerates

Not your chat. Open WebUI does not run LLMs; Ollama does. The image's own environment says what the CUDA build is for:

SENTENCE_TRANSFORMERS_HOME=/app/backend/data/cache/embedding/models
WHISPER_MODEL_DIR=/app/backend/data/cache/whisper/models
USE_CUDA_DOCKER_VER=cu128

Embeddings for document chat, and Whisper speech-to-text. If you don't use either, cuda buys you a much larger image and nothing else. If you do use them, it's the difference between instant and a visible pause.

The tag alone doesn't grant GPU access. You also have to uncomment gpus: all in compose.yaml and have the NVIDIA Container Toolkit installed on the host. Getting one without the other is the usual reason "the GPU isn't being used".

On Apple silicon, don't use `ollama`

Docker on macOS runs in a VM with no GPU passthrough — Metal is not reachable from a container. The bundled ollama tag will work and will be miserably slow, because inference falls back to CPU.

The right shape on a Mac is Ollama installed natively, where it uses Metal, with Open WebUI in Docker pointing at it:

OWUI_TAG=main
OLLAMA_BASE_URL=http://host.docker.internal:11434

Same applies to any machine where the GPU belongs to something other than Docker.

Why it looks like this

One compose file, not three. The three variants differ by an image tag and two optional lines. Keeping separate directories per variant meant fixing every bug three times, and the differences — the interesting part — weren't written down anywhere.

extra_hosts: host.docker.internal:host-gateway is always present, even though only the "Ollama on the host" case needs it. It costs nothing when unused and is the single most common thing people are missing when the WebUI can't see their models.

The Ollama volume is commented out. It's meaningless except with OWUI_TAG=ollama, and mounting it otherwise creates a stray empty directory that looks like it should contain something.

WEBUI_SECRET_KEY is optional and empty. The image generates one into the data directory on first run. That's fine until you move the data to another host, at which point a regenerated key logs everyone out.

Gotchas

Switching tags keeps your data. DATA_PATH holds chats, users and settings regardless of tag, so moving between main and ollama is safe. Your models are a different story — those live in OLLAMA_PATH and only exist for the bundled tag.
:main is a rolling tag. docker compose pull can bring a different version any day. Pin OWUI_TAG=v0.11.0 if you'd rather upgrade deliberately.
The container runs as root (User: 0:0 in the image config) and has no PUID/PGID support. On rootless Docker this is a non-issue; on rootful, expect DATA_PATH files to be root-owned.
The data directory gets big. It holds the RAG vector DB and cached embedding models, not just chats.

Exposing it

Reverse proxy with Caddy
Cloudflare Tunnel — fine for this one; chat is low-bandwidth. Watch the ~100 MB cap if you upload documents for RAG.
Single sign-on with Authentik — Open WebUI supports OIDC directly, which is nicer than forward auth here.

README.md