infra: deploy Open WebUI on hf-pdocker-01 with Ollama + Claude backends

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-11 14:13:16 -05:00
parent cd37bb9858
commit 59f529e3a7
6 changed files with 487 additions and 18 deletions
@@ -0,0 +1,148 @@
+# Open WebUI Deployment Design
+
+**Date:** 2026-03-11
+**Node:** hf-pdocker-01 (192.168.86.192)
+**Public URL:** https://open.hobbs.farm
+**Internal URL:** http://192.168.86.192:3010
+
+## Overview
+
+Deploy Open WebUI as a standalone Compose service on hf-pdocker-01, connected to Ollama (local GPU machine) and Anthropic Claude API. Publicly accessible via Traefik at `open.hobbs.farm`.
+
+## Architecture
+
+```
+Internet -> Traefik (hf-pdocker-01:443) -> http://192.168.86.192:3010 -> open-webui:8080
+                                                                            |
+                                                                            +-> Ollama (192.168.86.196:11434) [llava:13b + future models]
+                                                                            +-> Anthropic API (cloud) [Claude models]
+```
+
+## Service Definition
+
+- **Image:** `ghcr.io/open-webui/open-webui:main`
+- **Container name:** `open-webui`
+- **Internal port:** 8080 (container default)
+- **Host port:** 3010
+- **Memory:** `mem_limit: 1G`, `memswap_limit: 1G`
+- **Restart:** `unless-stopped`
+- **Watchtower:** `com.centurylinklabs.watchtower.enable=false` (manual upgrades)
+- **Timezone:** `TZ=America/Chicago`
+
+### Compose Location
+
+- Repo: `compose/hf-pdocker-01/openwebui/docker-compose.yml`
+- Deploy target: `/mnt/docker-data/compose/hf-pdocker-01/openwebui/`
+- `.env` file alongside compose for secrets (ANTHROPIC_API_KEY, WEBUI_SECRET_KEY)
+
+### Persistent Storage
+
+- Data volume: `/mnt/docker-data/configs/openwebui/` -> `/app/backend/data` in container
+- Stores: user accounts, chat history, settings, uploaded files
+- Open WebUI uses SQLite internally. Single-writer scenario on NFS is acceptable. If locking issues arise, fall back to local storage (like Guacamole's MySQL pattern at `/var/lib/`).
+- Container runs as root by default; NFS write permissions should work without `user: "1024:100"` but will be verified during deploy.
+
+### Environment Variables
+
+- `OLLAMA_BASE_URL=http://192.168.86.196:11434` — native Ollama connection
+- `ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}` — from .env, enables native Anthropic provider (Open WebUI v0.5+ has built-in Anthropic support)
+- `WEBUI_SECRET_KEY=${WEBUI_SECRET_KEY}` — from .env, generated via `openssl rand -hex 32`
+- `TZ=America/Chicago`
+
+### Healthcheck
+
+```yaml
+healthcheck:
+  test: ["CMD-SHELL", "curl -sf http://localhost:8080/health || exit 1"]
+  interval: 30s
+  timeout: 10s
+  retries: 3
+  start_period: 60s
+```
+
+### Logging
+
+```yaml
+logging:
+  driver: "json-file"
+  options:
+    max-size: "50m"
+    max-file: "3"
+```
+
+### Traefik Configuration
+
+Traefik on hf-pdocker-01 uses **file-based dynamic config** (no Docker provider/labels). A new dynamic config file is needed:
+
+- **Repo path:** `stacks/traefik/dynamic/openwebui.yml`
+- **Deploy target:** `/mnt/docker-data/traefik/dynamic/openwebui.yml` (auto-picked up by Traefik's file watcher)
+
+```yaml
+http:
+  routers:
+    openwebui:
+      rule: "Host(`open.hobbs.farm`)"
+      entryPoints:
+        - websecure
+      service: openwebui
+      tls:
+        certResolver: letsencrypt
+    openwebui-http:
+      rule: "Host(`open.hobbs.farm`)"
+      entryPoints:
+        - web
+      middlewares:
+        - openwebui-https-redirect
+      service: openwebui
+  middlewares:
+    openwebui-https-redirect:
+      redirectScheme:
+        scheme: https
+        permanent: true
+  services:
+    openwebui:
+      loadBalancer:
+        servers:
+          - url: "http://192.168.86.192:3010"
+```
+
+### Network
+
+- Default bridge network (single-container service, no custom network needed)
+- Traefik routes to `http://192.168.86.192:3010` via file-based config (no overlay network required)
+
+### Authentication
+
+- Built-in Open WebUI auth (email/password)
+- First user to register becomes admin
+- Admin disables open registration after initial setup
+
+### Monitoring
+
+- **Internal probe:** `http://192.168.86.192:3010` added to Prometheus `http-pdocker01` blackbox job
+- **External probe:** `https://open.hobbs.farm` added to Prometheus `http-external` blackbox job
+
+## LLM Backend Details
+
+### Ollama (Native)
+
+Open WebUI has first-class Ollama support. Setting `OLLAMA_BASE_URL` makes all Ollama models available in the model selector. Currently `llava:13b` is loaded; any future models pulled to Ollama will auto-appear.
+
+### Anthropic Claude (Native)
+
+Open WebUI v0.5+ has built-in Anthropic provider support. Setting the `ANTHROPIC_API_KEY` environment variable enables Claude models in the model selector. No proxy or OpenAI-compatibility layer needed. The existing API key (same one used by frigate-notify and AI agents) goes in the `.env` file.
+
+## Post-Deploy Checklist
+
+1. Verify container health and web UI loads at `http://192.168.86.192:3010`
+2. Verify Traefik routes `https://open.hobbs.farm` correctly
+3. Register first admin user
+4. Disable open registration in admin settings
+5. Verify Ollama models appear in model selector
+6. Verify Claude models appear in model selector
+7. Add Prometheus blackbox probes (internal + external)
+8. Hot-reload Prometheus: `curl -X POST http://192.168.86.192:9095/-/reload`
+9. Update CLAUDE.md service lists
+10. Update MEMORY.md
+11. Update wiki via documentation-keeper agent
+12. Store WEBUI_SECRET_KEY in Vaultwarden