consolidated openwebui

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 |
+| [openwebui](openwebui/) | 3033 | LLM chat UI. One `OWUI_TAG` switches between CPU, CUDA and bundled-Ollama |
-| [owui-ollama](owui-ollama/) | 3034 | Open WebUI bundled with Ollama |
 | [overleaf](overleaf/) | 8020 | LaTeX editor. Needs Mongo + Redis |
 
 <!-- One row per service. Add as you go — the table is the index people scan. -->

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=

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://<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:
+
+```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: <https://docs.openwebui.com/getting-started/quick-start>
+- Image: <https://github.com/open-webui/open-webui/pkgs/container/open-webui>

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://<its-ip>: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

openwebui/docker-compose.yaml

@@ -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

owui-ollama/docker-compose.yaml

@@ -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