# 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