Open WebUI

​

Overview

​

Architecture

• Open WebUI — A single-replica stateful workload serving the web UI and API on port 8080. Its public WEBUI_URL is derived from the canonical endpoint at boot, so links resolve correctly with no manual configuration.
• Embedded SQLite on a persistent volume — All durable state (the webui.db database, uploaded files, the default Chroma vector store used for RAG, and cache) lives on the workload’s volume set at /app/backend/data. SQLite is single-writer, so there is no external database dependency and the workload runs as exactly one replica.
• Model backends — Chat completions are served by an existing Ollama workload in the same GVC (default), an OpenAI-compatible API (optional), or both. Neither backend is bundled by this template — you point it at model providers you run or subscribe to.

​

What Gets Created

• Stateful Open WebUI Workload — A single replica serving the web UI and API on port 8080.
• Volume Set — A 10 GiB persistent volume mounted at /app/backend/data holding the SQLite database, uploaded files, the RAG vector store, and cache. Scheduled snapshots protect the data, and a final snapshot is kept on delete.
• Config Secret — Holds the stable WEBUI_SECRET_KEY that signs sessions and JWTs.
• Start-Script Secret — An opaque secret whose boot script sets WEBUI_URL from the canonical endpoint.
• Identity & Policy — An identity bound to the workload with a least-privilege policy granting reveal access to exactly the secrets it mounts (the config and start-script secrets, plus your OpenAI-key secret only when you configure one).

​

Prerequisites

• License awareness — Open WebUI ships under the “Open WebUI License” (BSD-3-Clause plus a branding-protection clause). It is free to self-host and run in production at any scale, but you must keep the “Open WebUI” branding visible in the UI unless your deployment serves 50 or fewer users, or you obtain enterprise permission. See Important Notes.
• Ollama backend (recommended) — An existing Ollama workload in the same GVC. Deploy the Ollama template first, then set its workload name in ollama.workloadName. Enabled by default.
• OpenAI-compatible backend (optional) — Create, before installing, an opaque secret (encoding: plain) in your org holding your API key, and set its name in openai.apiKeySecretName. An empty value leaves this backend off.

​

Configuration

image: ghcr.io/open-webui/open-webui:v0.11.0

resources:
  cpu: 1        # max vCPU
  memory: 2Gi   # max memory (RAG loads a local embedding model into RAM on first use)
  minCpu: 500m
  minMemory: 1Gi

# ─── Persistence ──────────────────────────────────────────────────────────────
# One per-replica volume holds everything durable: SQLite webui.db, uploaded
# files, the default Chroma vector store (RAG), and cache. Mounts /app/backend/data.
volumeset:
  capacity: 10 # GiB (platform minimum 10)

# ─── Backup ───────────────────────────────────────────────────────────────────
# Platform-managed crash-consistent snapshots (no cloud account/bucket needed).
backup:
  enabled: true
  schedule: "0 3 * * *" # cron in UTC — daily 03:00 (hourly is the platform max)
  retention: 7d         # how long each snapshot is kept (e.g. 7d, 720h, 30d)

# ─── Authentication ───────────────────────────────────────────────────────────
auth:
  # Signs sessions/JWTs. Override ONCE at install (openssl rand -base64 32).
  # Must stay STABLE across upgrades — changing it logs every user out.
  webuiSecretKey: "CHANGE-ME-openssl-rand-base64-32-abcdEFGH1234"
  enableSignup: true # first registered user becomes ADMIN — turn OFF after onboarding

# ─── Model backends ───────────────────────────────────────────────────────────
# Point at an existing `ollama` template deployment in this same GVC.
ollama:
  enabled: true
  workloadName: ollama # the ollama workload's name in this GVC
  port: 11434
  # → OLLAMA_BASE_URL = http://{workloadName}.{gvc}.cpln.local:{port}

# Optional OpenAI-compatible provider. The API key is a PREREQUISITE opaque
# secret (encoding: plain) you create BEFORE install; reference it by name here.
# Empty apiKeySecretName = this backend is off.
openai:
  baseUrl: https://api.openai.com/v1 # any OpenAI-compatible endpoint
  apiKeySecretName: "" # e.g. my-openwebui-openai-key ; empty = OpenAI backend off

# ─── Access ───────────────────────────────────────────────────────────────────
customDomain: "" # full URL, e.g. https://chat.example.com ; empty = canonical *.cpln.app

publicAccess:
  enabled: true # serve the UI over public HTTPS on the canonical *.cpln.app endpoint

internalAccess: # inbound firewall scope for in-GVC callers of the Open WebUI API
  type: none # options: none, same-gvc, same-org, workload-list
  workloads: [] # used with workload-list

​

Instance & Resources

• image — The Open WebUI container image.
• resources — CPU and memory for the container. RAG loads a local embedding model into RAM on first use, so keep memory at or above the default.
• volumeset.capacity — Volume size in GiB (minimum 10) for the SQLite database, uploads, RAG vector store, and cache.

​

Backup

• backup.enabled — Take periodic snapshots of the data volume (default true).
• backup.schedule — Cron expression in UTC (default 0 3 * * *, daily at 03:00). The platform does not accept schedules more frequent than hourly.
• backup.retention — How long each snapshot is kept, e.g. 7d, 720h, 30d.

​

Authentication

• auth.webuiSecretKey — Signs session tokens and JWTs. Override it once at install with openssl rand -base64 32, then keep it stable forever — see Important Notes.
• auth.enableSignup — Open registration on the public endpoint (default true so a fresh install is usable). The first account registered becomes the admin; turn this off after onboarding — see Important Notes.

​

Model backends

• ollama.enabled — Connect to an existing Ollama workload in this GVC (default true).
• ollama.workloadName — The Ollama workload’s name in this GVC. The base URL is derived as http://{workloadName}.{gvc}.cpln.local:{port}.
• ollama.port — The Ollama API port (default 11434).
• openai.baseUrl — Any OpenAI-compatible endpoint (default https://api.openai.com/v1).
• openai.apiKeySecretName — Name of your pre-created opaque secret holding the API key (see Prerequisites). Empty (default) leaves the OpenAI backend off.

​

Access

• customDomain — Full URL of a custom domain, e.g. https://chat.example.com. Empty (default) uses the canonical *.cpln.app endpoint.
• publicAccess.enabled — Serve the UI over public HTTPS on the canonical *.cpln.app endpoint (default). When disabled, external requests are blocked at the edge and only in-GVC callers reach it per internalAccess.
• internalAccess.type — Internal firewall scope for in-GVC callers of the Open WebUI API:

​

Connecting

​

Using a Model Backend

​

Backing Up

• Default schedule — Daily at 03:00 UTC (backup.schedule: "0 3 * * *"), kept for 7 days (backup.retention: 7d).
• Minimum interval — The platform does not accept schedules more frequent than hourly.

cpln volumeset snapshot get {release}-open-webui-data --gvc {gvc} -o yaml

​

Restoring a Backup

cpln volumeset snapshot get {release}-open-webui-data --gvc {gvc} -o yaml

cpln volumeset snapshot restore {release}-open-webui-data \
  --snapshot-name <snapshot-name> \
  --location <location> \
  --volume-index 0 \
  --gvc {gvc}

​

Important Notes

• License / branding clause — You must keep the “Open WebUI” branding visible in the UI unless your deployment serves 50 or fewer users, or you have enterprise permission. Removing the branding outside those cases violates the license; it is not a template setting.
• The first user to register becomes the admin. Sign-ups are open by default so the install is immediately usable, which means anyone reaching the public endpoint can register while it is open. Register your admin account first, then set auth.enableSignup=false to lock it down.
• auth.webuiSecretKey must never change after first install. It is the key that signs session tokens and JWTs. Rotating it — or letting a fresh volume regenerate one — logs every user out. Override it once with openssl rand -base64 32 and keep it stable.
• Single replica, by design. The embedded SQLite is single-writer and the volume set is per-replica, so the workload is pinned to one replica with no replicas knob. A restart or upgrade is a brief full outage (about a minute).
• Model-backend settings apply at install, then persist in the app database. ollama.workloadName and openai.* are read from the environment only on the first boot and then stored in webui.db. Changing them via a later helm upgrade is silently ignored — update model connections afterward from the admin UI (Settings → Connections).
• Data lives only on the volume set. Uninstall deletes it (a final snapshot is taken first); a reinstall starts empty. Changing the secret and redeploying does not re-key existing data.
• Backups are in-platform, not off-site. Scheduled snapshots and the final snapshot on uninstall live in the platform storage layer next to the volume; losing the whole GVC would lose them too. See Backing Up.

​

External References