hobbs-iac/docs/superpowers/specs/2026-03-11-openwebui-design.md

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

healthcheck:
  test: ["CMD-SHELL", "curl -sf http://localhost:8080/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

Logging

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)

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