Open WebUI

​

Overview

​

Architecture

• Open WebUI — A single-replica stateful workload serving the web UI and API on port 8080. A mounted start script sets its public WEBUI_URL 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.
• No template-created credential — The key that signs sessions and JWTs lives only in a secret you create yourself, so it never enters the Helm release.

​

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.
• 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: your session-key secret, the start-script secret, and your OpenAI-key secret only when you configure one.

​

Prerequisites

printf '%s' "$(openssl rand -base64 32)" | cpln secret create-opaque --name my-openwebui-secret-key --encoding plain -f -

​

First Run

cpln workload get-deployments {release}-open-webui --gvc {gvc}

cpln port-forward {release}-open-webui 8080:8080 --gvc {gvc}

cpln workload exec {release}-open-webui --gvc {gvc} --container open-webui -- \
  curl -sS -X POST http://localhost:8080/api/v1/auths/signup \
  -H 'Content-Type: application/json' \
  -d '{"name":"Admin","email":"admin@example.com","password":"YOUR-STRONG-PASSWORD"}'

​

Configuration

# ─── Image & Resources ────────────────────────────────────────────────────────
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).
# SQLite recovers cleanly from a snapshot. A final snapshot is taken on uninstall.
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:
  # REQUIRED opaque secret (encoding: plain) holding the session/JWT signing key.
  # It must EXIST BEFORE INSTALL — the deployment wedges waiting on it otherwise —
  # and must stay the same forever: replacing it logs every user out.
  # Create it with: printf '%s' "$(openssl rand -base64 32)" | cpln secret create-opaque --name my-openwebui-secret-key --encoding plain -f -
  secretKeyName: my-openwebui-secret-key
  # false = nobody can create their own account. The FIRST account is exempt, so
  # you can still register the admin on a fresh install (see the README first-run
  # steps); invite everyone else from Admin Settings → Users.
  enableSignup: false

# ─── 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 ───────────────────────────────────────────────────────────────────
# Sets WEBUI_URL only — it does NOT create a cpln domain. Create and verify the
# domain separately, or the hostname will not resolve. Read at FIRST BOOT ONLY
# (see Important Notes); set it at install, not in a later upgrade.
customDomain: "" # full URL, e.g. https://chat.example.com ; empty = canonical *.cpln.app

publicAccess:
  # false = not reachable from the internet. Turning this on publishes the chat
  # UI, and its sign-in/sign-up form, to the whole internet — so register your
  # admin account FIRST (see the README first-run steps), then turn it on.
  enabled: false

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
  # workloads:
  #   - //gvc/GVC_NAME/workload/WORKLOAD_NAME

​

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.secretKeyName — Name of the opaque secret holding the session and JWT signing key. It must exist before you install (see Prerequisites) and must never change afterward.
• auth.enableSignup — Whether users can create their own accounts (default false). The first account on a fresh install is exempt, so a default install is still usable — that is how you create the admin in First Run.

​

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). The workload’s outbound firewall is open, so hosted providers such as api.openai.com are reachable.
• openai.apiKeySecretName — Name of your pre-created opaque secret holding the API key (see Prerequisites). Empty (default) leaves the OpenAI backend off, and the policy grants no access to any key secret.

​

Access

• customDomain — Full URL of a custom domain, e.g. https://chat.example.com. The scheme is required; the chart fails the render without it. Empty (default) uses the canonical *.cpln.app endpoint.
• publicAccess.enabled — Serve the UI over public HTTPS on the canonical *.cpln.app endpoint (default false). While it is off, external requests are rejected at the edge with 403 and only in-GVC callers reach the workload, 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

• Create the session-key secret before installing, and never change it. auth.secretKeyName only names the secret; the workload wedges waiting on one that does not exist. The key signs every session and JWT, so replacing it logs every user out.
• The first account registered becomes the administrator. That is why the UI ships private with sign-ups closed — an unclaimed admin account on a public URL belongs to whoever finds it first. Claim it over a port-forward before turning publicAccess.enabled on; see First Run.
• auth.enableSignup is only read while no account exists. After the first account it is stored in webui.db and the stored value wins, so a later helm upgrade can neither open nor close sign-ups. Use Admin Settings → Users instead.
• ollama.*, openai.* and customDomain apply at install, then persist in the app database. A later helm upgrade is ignored and the old backend keeps working, so there is no symptom to warn you. Change model connections from the admin UI under Settings → Connections.
• customDomain does not create a domain. It sets WEBUI_URL only; create the Control Plane domain and its DNS separately, or the hostname will not resolve while the install reports success.
• Restoring a snapshot is manual and loses post-snapshot data, including accounts created after it was taken. See Restoring a Backup.
• 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 of about a minute — including the first helm upgrade after an install, which re-applies the workload even when nothing changed.
• Data lives only on the volume set. Uninstall deletes it (a final snapshot is taken first); a reinstall starts empty, including the admin account. Your own prerequisite secrets are not deleted, since the chart does not own them.
• Ollama unreachable is non-fatal. The UI boots and shows no Ollama models rather than failing, so check the model list after install.
• 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.

​

External References