From 3c4b63d29593e8f8540569f8393f89eb23789a09 Mon Sep 17 00:00:00 2001 From: Goyban Date: Mon, 24 Aug 2026 13:47:19 +0200 Subject: [PATCH] consolidated openwebui --- README.md | 3 +- openwebui/.env.example | 44 +++++++++++++ openwebui/README.md | 113 ++++++++++++++++++++++++++++++++ openwebui/compose.yaml | 41 ++++++++++++ openwebui/docker-compose.yaml | 16 ----- owui-ollama/docker-compose.yaml | 18 ----- 6 files changed, 199 insertions(+), 36 deletions(-) create mode 100644 openwebui/.env.example create mode 100644 openwebui/README.md create mode 100644 openwebui/compose.yaml delete mode 100644 openwebui/docker-compose.yaml delete mode 100644 owui-ollama/docker-compose.yaml diff --git a/README.md b/README.md index c0fbda8..44db654 100644 --- a/README.md +++ b/README.md @@ -39,8 +39,7 @@ handled separately — see [Exposing services](#exposing-services). | [audiobookshelf](audiobookshelf/) | 13378 | Audiobooks and podcasts, with per-user progress sync | | [cloudflare-tunnel](cloudflare-tunnel/) | — | Outbound connector. Exposes other services without opening a port | | [jellyfin](jellyfin/) | 8096 | Media streaming. Also 7359/udp for auto-discovery | -| [openwebui](openwebui/) | 3033 | LLM chat UI, talks to an external model backend | -| [owui-ollama](owui-ollama/) | 3034 | Open WebUI bundled with Ollama | +| [openwebui](openwebui/) | 3033 | LLM chat UI. One `OWUI_TAG` switches between CPU, CUDA and bundled-Ollama | | [overleaf](overleaf/) | 8020 | LaTeX editor. Needs Mongo + Redis | diff --git a/openwebui/.env.example b/openwebui/.env.example new file mode 100644 index 0000000..ef8d8fb --- /dev/null +++ b/openwebui/.env.example @@ -0,0 +1,44 @@ +# Copy to .env and adjust. .env is git-ignored; this file is not. + +# ─── Which image ──────────────────────────────────────────────────── +# This is the only setting that changes what the stack actually is. +# README.md has the full comparison; the short version: +# +# main WebUI only, CPU. Models run somewhere else. (default) +# latest identical to main — both are the same rolling build +# cuda + CUDA runtime. Speeds up RAG embeddings and Whisper STT, +# NOT chat. Needs an NVIDIA host + Container Toolkit. +# ollama + Ollama bundled inside the same container. +# v0.11.0 a frozen release. main/latest move under you. +# +#OWUI_TAG=main + +# With OWUI_TAG=cuda or ollama on an NVIDIA host, also uncomment +# `gpus: all` in compose.yaml — the tag alone does not grant GPU access. + +# ─── Where the models are ─────────────────────────────────────────── +# Skip this and set it in the UI instead if you prefer. +# Ollama on the Docker host http://host.docker.internal:11434 +# Ollama in another container http://ollama:11434 +# Ollama on a Mac or other box http://192.168.1.x:11434 +# OWUI_TAG=ollama leave unset — it is already local +#OLLAMA_BASE_URL=http://host.docker.internal:11434 + +# ─── Paths ────────────────────────────────────────────────────────── +# Chats, users, settings, RAG vector DB and model caches. Back this up. +#DATA_PATH=./open-webui + +# Pulled Ollama models. ONLY used with OWUI_TAG=ollama, and only if you +# uncomment the matching line in compose.yaml. Tens of GB. +#OLLAMA_PATH=./ollama + +# ─── Ports ────────────────────────────────────────────────────────── +#PORT=3033 + +#TZ=Europe/Paris + +# ─── Optional ─────────────────────────────────────────────────────── +# Signs session cookies. Generated into DATA_PATH when unset, which is fine +# for a single instance. Set it explicitly if you move the data between +# hosts, otherwise everyone gets logged out. +#WEBUI_SECRET_KEY= diff --git a/openwebui/README.md b/openwebui/README.md new file mode 100644 index 0000000..952ac14 --- /dev/null +++ b/openwebui/README.md @@ -0,0 +1,113 @@ +# 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 + +```bash +cp .env.example .env +$EDITOR .env # pick OWUI_TAG, point it at your models +docker compose up -d +``` + +Open `http://: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: + +```bash +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](../docs/reverse-proxy.md) +- [Cloudflare Tunnel](../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](../docs/authentik-sso.md) — Open WebUI + supports OIDC directly, which is nicer than forward auth here. + +## Links + +- Quick start: +- Image: diff --git a/openwebui/compose.yaml b/openwebui/compose.yaml new file mode 100644 index 0000000..e9a42ed --- /dev/null +++ b/openwebui/compose.yaml @@ -0,0 +1,41 @@ +services: + open-webui: + # The TAG decides what is inside the image — full comparison in README.md. + # main / latest WebUI only, CPU. Models live elsewhere. (default) + # cuda + CUDA runtime for RAG embeddings and STT + # ollama + Ollama bundled in the same container + # v0.11.0 a frozen release; main/latest are rolling + image: ghcr.io/open-webui/open-webui:${OWUI_TAG:-main} + container_name: open-webui + restart: unless-stopped + + environment: + - TZ=${TZ:-Etc/UTC} + # Where the models are. Leave commented to pick it in the UI instead. + # Ollama on the Docker host -> http://host.docker.internal:11434 + # Ollama in another container -> http://ollama:11434 + # Ollama on a Mac / another box -> http://:11434 + # OWUI_TAG=ollama (bundled) -> leave unset, it is already local + #- OLLAMA_BASE_URL=${OLLAMA_BASE_URL} + # Session signing key. Generated into the data dir when unset — set it + # explicitly if you ever move the data to another host. + #- WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY} + + volumes: + - ${DATA_PATH:-./open-webui}:/app/backend/data + # ONLY with OWUI_TAG=ollama — where pulled models are stored. Expect tens + # of GB. Leave commented for every other tag. + #- ${OLLAMA_PATH:-./ollama}:/root/.ollama + + ports: + - "${PORT:-3033}:8080" + + # Lets the container reach an Ollama running on the Docker host. + extra_hosts: + - host.docker.internal:host-gateway + + # ─── NVIDIA GPU ────────────────────────────────────────────────────── + # Uncomment with OWUI_TAG=cuda or OWUI_TAG=ollama on an NVIDIA host. + # Needs the NVIDIA Container Toolkit installed. Does nothing on Apple + # silicon — Docker cannot reach the GPU there at all. See the README. + #gpus: all diff --git a/openwebui/docker-compose.yaml b/openwebui/docker-compose.yaml deleted file mode 100644 index 3ee34d4..0000000 --- a/openwebui/docker-compose.yaml +++ /dev/null @@ -1,16 +0,0 @@ -name: openwebui -services: - open-webui: - ports: - - 3033:8080 - extra_hosts: - - host.docker.internal:host-gateway - volumes: - - ./open-webui:/app/backend/data - container_name: open-webui - restart: always - image: ghcr.io/open-webui/open-webui:main -volumes: - open-webui: - external: true - name: open-webui diff --git a/owui-ollama/docker-compose.yaml b/owui-ollama/docker-compose.yaml deleted file mode 100644 index d99ef79..0000000 --- a/owui-ollama/docker-compose.yaml +++ /dev/null @@ -1,18 +0,0 @@ -name: obwi-with-ollama -services: - open-webui: - ports: - - 3034:8080 - volumes: - - ./ollama:/root/.ollama - - ./open-webui:/app/backend/data - container_name: open-webui - restart: always - image: ghcr.io/open-webui/open-webui:ollama -volumes: - ollama: - external: true - name: ollama - open-webui: - external: true - name: open-webui