# Open-WebUI

## Overview

Open Web UI is the primary chat and AI management interface for the homelab. It
provides a ChatGPT-style web frontend connected to the local Ollama backend, with
support for conversation history, model selection, RAG (document chat), image
generation, and tool use. It can also proxy to external OpenAI-compatible APIs.

## Access

| Type      | URL                               | Notes                                         |
|-----------|-----------------------------------|-----------------------------------------------|
| Internal  | `https://ai.home.local`           | LAN access via Step-CA TLS                    |
| External  | `https://ai.jeeves5454.ddns.net`  | Internet-facing — Authentik SSO + GeoBlock + CrowdSec |

## Configuration

**Image:** `ghcr.io/open-webui/open-webui:main`
**Compose project:** `ai-stack`

### Ports

| Port   | Protocol | Purpose                              |
|--------|----------|--------------------------------------|
| `3015` | TCP      | Web UI (mapped from internal `8080`) |

### Traefik Labels

```yaml
# Internal route
traefik.http.routers.openwebui-internal.rule: Host(`ai.home.local`)
traefik.http.routers.openwebui-internal.entrypoints: websecure
traefik.http.routers.openwebui-internal.tls.certresolver: step-ca
traefik.http.routers.openwebui-internal.service: openwebui-svc

# External route
traefik.http.routers.openwebui-external.rule: Host(`ai.jeeves5454.ddns.net`)
traefik.http.routers.openwebui-external.entrypoints: websecure
traefik.http.routers.openwebui-external.tls.certresolver: letsencrypt
traefik.http.routers.openwebui-external.middlewares: authentik-auth@docker,plex-geoblock@file,crowdsec-bouncer@file
traefik.http.routers.openwebui-external.service: openwebui-svc

traefik.http.services.openwebui-svc.loadbalancer.server.port: 8080
```

### Environment Variables

| Variable                       | Value / Notes                                    |
|--------------------------------|--------------------------------------------------|
| `WEBUI_AUTH`                   | `False` — authentication handled by Authentik    |
| `ENABLE_OLLAMA_API`            | `True`                                           |
| `ENABLE_OPENAI_API`            | `True`                                           |
| `ENABLE_IMAGE_GENERATION`      | `True`                                           |
| `IMAGE_GENERATION_ENGINE`      | `automatic1111`                                  |
| `IMAGE_GENERATION_MODEL`       | `dreamshaper_8`                                  |
| `IMAGE_SIZE`                   | `400x400`                                        |
| `IMAGE_STEPS`                  | `8`                                              |
| `AUTOMATIC1111_BASE_URL`       | `http://stable-diffusion:7860/`                  |
| `AUTOMATIC1111_CFG_SCALE`      | `2`                                              |
| `AUTOMATIC1111_SAMPLER`        | `DPM++ SDE`                                      |
| `AUTOMATIC1111_SCHEDULER`      | `Karras`                                         |

> `WEBUI_AUTH=False` disables Open Web UI's own login page. Authentication is
> delegated entirely to Authentik ForwardAuth on the external route. On the
> internal LAN route, the interface is open — access is controlled by network
> boundary only.

## Volumes / Bind Mounts

| Host Path / Volume                  | Container Path        | Purpose                        |
|-------------------------------------|-----------------------|--------------------------------|
| `open_webui_open-webui-data`        | `/app/backend/data`   | Conversation history, settings, uploaded docs (named volume, external) |

## Networks

| Network                 | Purpose                                         |
|-------------------------|-------------------------------------------------|
| `ai-stack_ai-internal`  | Reaches Ollama backend on `ai-internal` network |
| `traefik-net`           | Exposes the web UI via Traefik                  |

## Dependencies

- `ollama` — must be running for model inference; Open Web UI will start without it
  but model requests will fail
- Authentik — required for external route SSO; LAN route is unaffected if Authentik
  is down

## Notes / Gotchas

- The `main` image tag tracks the latest development build. For stability, consider
  pinning to a tagged release (e.g. `v0.6.x`).
- `WEBUI_AUTH=False` means **anyone on the LAN** can access the internal URL without
  credentials. If untrusted devices are on the LAN, consider enabling WEBUI_AUTH and
  creating user accounts, or adding Authentik middleware to the internal route as well.
- Conversation history and user settings are stored in the named Docker volume. Back
  this up before upgrades.
- Open Web UI admin panel is at `https://ai.home.local/admin/` — first user to register
  (if auth is enabled) becomes the admin.
- Image generation requires the stable-diffusion container to be running (separate
  service, also on `ai-internal` network).

---
*Last Updated: 2026-06-16*