Open WebUI

Overview

Open WebUI is a self-hosted, ChatGPT-style chat interface for large language models with user accounts, RAG (chat grounded in your uploaded documents), and model management. This template deploys a single-replica stateful workload that keeps all of its state on a persistent volume and connects to your models through an OpenAI-compatible API (such as the vLLM template or a hosted provider), an Ollama workload in the same GVC, or both. Neither backend is bundled: you point the template at model providers you already run or subscribe to. The administrator account comes from a secret you create before installing, and self-service sign-up is off, so the UI is ready to sign in to on its public URL as soon as it starts. The Control Plane MCP server is added as a tool server, so each user can connect their own Control Plane account and manage it from a chat.

This template does not create a GVC. You must deploy it into an existing GVC that you already have.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-open-webui`	Open WebUI server and API (stateful, 1 replica, HTTP port `8080`)	—
Volume Set	`RELEASE_NAME-open-webui-data`	10 GiB volume at `/app/backend/data` holding the SQLite database, uploaded files, the RAG vector store, and cache; scheduled snapshots, final snapshot on delete	—
Secret	`RELEASE_NAME-open-webui-start`	Start script that sets `WEBUI_URL` from the canonical endpoint and, with `cplnMcp.enabled`, adds the Control Plane MCP server once per install	—
Identity	`RELEASE_NAME-open-webui-identity`	Identity bound to the workload	—
Policy	`RELEASE_NAME-open-webui-policy`	Grants the identity `reveal` on exactly the secrets the workload reads: your session-key and admin secrets, the start-script secret, and your OpenAI-key secret only when you configure one	—

The template creates no credential of its own. The admin account and the key that signs sessions and JWTs live only in secrets you create, so they never enter the Helm release.

Prerequisites

Two secrets must exist before you install: the admin account and the session signing key. Both are long-lived credentials, so they are secrets you own rather than Helm values. Secrets are org-level, so no GVC flag is involved.

Create the admin account secret

Store the administrator’s email and password in a dictionary secret with the keys email and password. Open WebUI creates this administrator on its first boot, before it serves anything, and turns self-service sign-up off:

cpln secret create-dictionary --name ADMIN_SECRET_NAME \
  --entry email=you@example.com \
  --entry password='YOUR-STRONG-PASSWORD'

Set admin.secretName to this name. The secret is read on the first boot only; change the password later in the UI (Settings → Account).

Create the session signing key secret

Generate a random key and store it as the payload of an opaque secret with plain encoding:

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

Set auth.secretKeyName to this name. The key signs every session and JWT: keep it forever, because replacing it signs every user out. Read it back with -o yaml; a bare cpln secret reveal prints only a summary table:

cpln secret reveal SESSION_KEY_SECRET_NAME -o yaml

Optional: create the OpenAI-compatible API key secret

Only when you use a hosted or OpenAI-compatible provider. Store the provider’s API key as the payload of another opaque secret:

printf '%s' 'YOUR-PROVIDER-API-KEY' | cpln secret create-opaque --name OPENAI_KEY_SECRET_NAME --encoding plain -f -

Set openai.apiKeySecretName to this name. When pairing with the vLLM template, reuse vLLM’s own API key secret instead (see Pairing with vLLM). Leaving it empty (the default) keeps this backend off.

Optional: have an Ollama workload in the same GVC

The Ollama backend is off by default. To use it, deploy the Ollama template into this GVC, pull at least one model, and set ollama.enabled: true and ollama.workloadName to that workload’s name.

Create both secrets before installing, or the deployment wedges silently. A name that points at a secret which does not exist installs “successfully” and then never starts. The container never runs, so cpln logs returns zero lines. The one place the reason appears is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-open-webui --gvc GVC_NAME -o yaml

The secret SESSION_KEY_SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Use get-deployments; plain cpln workload get has no versions key. Once the secret exists the workload recovers on its own after a wait, so keep polling, or run cpln workload force-redeployment RELEASE_NAME-open-webui --gvc GVC_NAME to skip it.

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. Backups need nothing further: they are platform-managed volume snapshots with no bucket or cloud account involved. See Backing Up.

Installation

Install from the marketplace registry with the two required values, the names of the secrets you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/open-webui \
  --version 1.3.0 --gvc GVC_NAME \
  --set auth.secretKeyName=SESSION_KEY_SECRET_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME

Add --set openai.baseUrl=... and --set openai.apiKeySecretName=OPENAI_KEY_SECRET_NAME for an OpenAI-compatible backend, or --set ollama.enabled=true --set ollama.workloadName=OLLAMA_WORKLOAD_NAME for Ollama. Model-backend values are read on the first boot only, so set them at install (see Model Backends). Then follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

One subsection per top-level values area. Each block shows the shipped defaults.

Image and Resources

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

resources:
  maxCpu: 1        # max vCPU
  maxMemory: 2Gi   # max memory (first boot downloads a ~900 MB RAG embedding model from huggingface.co and loads it into RAM)
  minCpu: 500m
  minMemory: 1Gi

image — The Open WebUI container image.
resources.minCpu / resources.minMemory — CPU and memory reserved for the container.
resources.maxCpu / resources.maxMemory — The container’s limits. The first boot loads a local RAG embedding model into RAM, so keep maxMemory at or above the default.

On a stateful workload the ratio of maxCpu to minCpu may not exceed 4:1. The shipped 1 / 500m is 2:1; raising maxCpu without raising minCpu can cross the limit and is rejected when the workload is applied.

Persistence and Backup

volumeset:
  capacity: 10 # GiB (platform minimum 10)

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)

volumeset.capacity — Volume size in GiB (minimum 10) for the SQLite database, uploads, RAG vector store, and cache at /app/backend/data.
backup.enabled — Take scheduled snapshots of the data volume. Snapshots are platform-managed; no cloud account or bucket is needed.
backup.schedule — Cron expression in UTC with a single fixed minute. The chart refuses a schedule more frequent than hourly.
backup.retention — How long each snapshot is kept, for example 7d, 720h, 30d.

See Backing Up and Restoring a Backup.

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

# REQUIRED dictionary secret with keys `email` and `password`: the admin account,
# created at first boot before the UI serves anything (sign-up then stays off).
# It must EXIST BEFORE INSTALL. Read on first boot only; change the password in the UI.
# Create it with: cpln secret create-dictionary --name my-openwebui-admin --entry email=you@example.com --entry 'password=...'
admin:
  secretName: my-openwebui-admin

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 afterwards.
admin.secretName — Name of the dictionary secret (keys email, password) the administrator is created from. It is read only while the database has no accounts, so changing the secret later changes nothing.

Self-service sign-up is not a template setting. It is off on a fresh install; add users from Admin Panel → Users, or open sign-up from Settings → Admin → Authentication (New Sign Ups).

Model Backends

# Point at an existing `ollama` template deployment in this same GVC.
ollama:
  enabled: false # true = connect to an existing ollama workload in this GVC
  workloadName: "" # its workload name, e.g. my-ollama-ollama for an ollama release named my-ollama; required when enabled
  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

At least one backend is needed to chat. Both are off by default; you can enable both.

ollama.enabled — Connect to an existing Ollama workload in this GVC.
ollama.workloadName — That workload’s name; required when ollama.enabled is true. The Ollama template names its workload after its release name followed by -ollama. The base URL is always fully qualified: http://OLLAMA_WORKLOAD_NAME.GVC_NAME.cpln.local:11434.
ollama.port — The Ollama API port.
openai.baseUrl — The provider’s API base URL. The shipped default is the hosted OpenAI v1 API; set it to any OpenAI-compatible endpoint.
openai.apiKeySecretName — Name of the opaque secret holding the provider’s API key (see Prerequisites). Empty leaves this backend off and the policy grants no access to any key secret.

Backend settings apply on the first boot only, and a later change fails silently. ollama.*, openai.* and customDomain are read from the environment the first time the workload starts and are then stored in the application database; a later upgrade is ignored. Nothing looks wrong, because the original backend keeps working. Set these at install, and change model connections afterwards in Settings → Admin → Connections.

Control Plane MCP

# Adds the Control Plane MCP server (https://mcp.cpln.io) as a tool server, once per
# install, signing in as the admin from admin.secretName. Each user then connects their
# own Control Plane account, so tools act with that user's permissions.
cplnMcp:
  enabled: true # false = no Control Plane tool server

cplnMcp.enabled — Add the Control Plane MCP server as a tool server. It is added once per install, so an administrator who removes it keeps it removed. Each user connects their own Control Plane account, so the tools act with that user’s Control Plane permissions. See Connecting Control Plane Tools.

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:
  # true = the chat UI and its sign-in form are on the canonical *.cpln.app URL.
  # Safe by default: the admin exists before the UI serves and sign-up is off.
  enabled: true

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

customDomain — Full URL of a custom domain, for example https://chat.example.com. The scheme is required; the chart fails the render without it. Empty uses the canonical *.cpln.app endpoint.
publicAccess.enabled — Serve the chat UI and its sign-in form over public HTTPS on the canonical *.cpln.app endpoint. Set it to false to keep the UI off the internet.
internalAccess.type — Inbound firewall scope for in-GVC callers of the Open WebUI API on port 8080:

Type	Description
`none`	No internal access (default).
`same-gvc`	Allow access from all workloads in the same GVC.
`same-org`	Allow access from all workloads in the same org.
`workload-list`	Allow access only from workloads listed in `internalAccess.workloads`.

customDomain sets WEBUI_URL and nothing else. It does not create a Control Plane domain, and the install succeeds with no error if none exists; the hostname simply never resolves and the canonical endpoint remains the only way in. Create and verify the domain separately. Because the value is also frozen after the first boot, set it at install rather than adding it to a running release.

An access change takes up to a few minutes to take effect. Re-test before concluding that a firewall value did not work.

Pairing with vLLM

To chat with a model served by the vLLM template in the same GVC, point the OpenAI-compatible backend at vLLM’s internal address and reuse vLLM’s API key secret. The vLLM workload is named after its release name followed by -vllm:

ollama:
  enabled: false
openai:
  baseUrl: http://VLLM_WORKLOAD_NAME.GVC_NAME.cpln.local:8000/v1  # vLLM's internal API
  apiKeySecretName: VLLM_API_KEY_SECRET_NAME                    # the same secret as vLLM's apiKey.secretName

vLLM must allow the caller (its default internalAccess.type: same-gvc does) and keep model.toolCallParser set. Open WebUI offers tools on every chat, and vLLM rejects those requests without it.
vLLM’s default model and 8192-token context are fine for chat; the Control Plane tools need a 64k context (see Connecting Control Plane Tools).
Images (Capture and image uploads) need a vision model. A text model such as Qwen2.5-7B-Instruct rejects them with is not a multimodal model.
Set these at install: the backend settings are read on the first boot only. Change them later in Settings → Admin → Connections.

Connecting

What	Address	Notes
Web UI (public)	`status.canonicalEndpoint` of the workload	With `publicAccess.enabled: true` (the default). Read it with `cpln workload get RELEASE_NAME-open-webui --gvc GVC_NAME -o yaml`
Internal API	`http://RELEASE_NAME-open-webui.GVC_NAME.cpln.local:8080`	Only when `internalAccess.type` allows the caller
From your machine	`http://localhost:8080` through `cpln port-forward RELEASE_NAME-open-webui 8080:8080 --gvc GVC_NAME`	Fine for API calls; browsers stall through the tunnel, so use the public URL for the UI
Ollama backend	`http://OLLAMA_WORKLOAD_NAME.GVC_NAME.cpln.local:11434`	The existing Ollama workload named in `ollama.workloadName`
Login	The `email` and `password` in your admin secret	`cpln secret reveal ADMIN_SECRET_NAME -o yaml`; add other users from Admin Panel → Users
Session signing key	`cpln secret reveal SESSION_KEY_SECRET_NAME -o yaml`	The payload of your `auth.secretKeyName` secret; never in the Helm release

First Run

Create the secrets and install

Create the admin and session-key secrets (see Prerequisites), then install with both names set.

Wait for the workload to be ready

cpln workload get-deployments RELEASE_NAME-open-webui --gvc GVC_NAME -o yaml

Read the canonical endpoint from status.canonicalEndpoint:

cpln workload get RELEASE_NAME-open-webui --gvc GVC_NAME -o yaml

Open it in a browser and sign in with the email and password from your admin secret.

Share models with your users

New users see no models until you share them. In Settings → Admin → Models, open each model’s Access and make it Public, or grant it to users or groups.

Connecting Control Plane Tools

With cplnMcp.enabled: true, the Control Plane MCP server is ready to use. Each user connects their own account, so the tools act with that user’s Control Plane permissions:

Switch on the Control Plane tools

In a chat, click the Integrations icon (next to +), choose Tools, and switch on Control Plane.

Ask a question

Ask, for example, “list my GVCs”.

The model must support tool calling and a context of at least 64k tokens: the Control Plane tool list alone is about 56k tokens, sent with every message. With vLLM, keep model.toolCallParser set; Qwen2.5-7B-Instruct reaches 64k with YaRN, set in the vLLM template’s values:

model:
  name: Qwen/Qwen2.5-7B-Instruct
  maxModelLen: 65536
  extraArgs:
    - --hf-overrides
    - '{"max_position_embeddings":65536,"rope_parameters":{"rope_type":"yarn","factor":2.0,"original_max_position_embeddings":32768,"rope_theta":1000000.0}}'

To add the server by hand (for example after an upgrade whose admin secret did not match), open Settings → Admin → Integrations → External Tool Servers → +, switch Type to MCP, and enter Name Control Plane, ID cpln, URL https://mcp.cpln.io/mcp, Auth OAuth 2.1. Click Register Client, then Save.

Using a Model Backend

Install with an OpenAI-compatible backend (a hosted provider, or the vLLM template as in Pairing with vLLM), or with ollama.enabled: true and ollama.workloadName set to an Ollama workload with at least one model pulled; the backend’s models appear in the model picker. If a configured Ollama backend is unreachable the UI still boots and simply shows no Ollama models. Because backend values are frozen after the first boot, correct a connection in Settings → Admin → Connections rather than by upgrading.

Operations

Backing Up

Backups are scheduled volume snapshots managed by the platform; no cloud account or bucket is required. On the configured schedule the platform snapshots the data volume, and SQLite recovers cleanly from one. Snapshots are pruned after backup.retention, and a final snapshot is always taken when the release is uninstalled.

Default schedule — Daily at 03:00 UTC (backup.schedule: "0 3 * * *"), kept for 7 days (backup.retention: 7d).
Minimum interval — Hourly; the chart refuses a more frequent schedule.

List the snapshots of the release’s volume set:

cpln volumeset snapshot get RELEASE_NAME-open-webui-data --gvc GVC_NAME

Snapshots live in the platform storage layer alongside the volume, not off-site. They protect against data corruption and accidental changes, but losing the whole GVC would lose them too.

Restoring a Backup

There is no automated restore. backup.enabled only takes snapshots; recovering from one is a manual, deliberate operation that restores the chosen snapshot onto the release’s own volume set, after which the workload restarts onto the restored data. You can do it from the Control Plane console or with the CLI.

Restoring reverts the volume to the exact snapshot state, so everything written after the snapshot is gone, including user accounts. A user added after the snapshot was taken can no longer sign in. It also restarts the single-replica workload, so the UI is unavailable during the restore.

Find the snapshot to restore

List snapshots and note the name, location, and volume index of the one you want:

cpln volumeset snapshot get RELEASE_NAME-open-webui-data --gvc GVC_NAME

Restore it onto the volume set

The release has one replica, so the volume index is 0:

cpln volumeset snapshot restore RELEASE_NAME-open-webui-data --gvc GVC_NAME \
  --snapshot-name SNAPSHOT_NAME \
  --location LOCATION \
  --volume-index 0

This command shape is taken from the CLI’s own help and has not been run against this template from these docs. Treat the CLI path as unverified: rehearse it on a throwaway release, or use the console, before you depend on it.

Verify

Once the workload is ready again, sign in and confirm your chats, uploads and settings are present.

Upgrading from 1.0.0

Template version 1.1.0 moved the session/JWT signing key out of Helm values into a prerequisite secret. A release coming from 1.0.0 also takes the later changes, so follow Upgrading from 1.1.0 and Upgrading from 1.2.0 as well.

Carrying auth.webuiSecretKey forward stops the upgrade. The key is rejected at render, so the upgrade fails and your running release is left untouched:

Error: ... open-webui: auth.webuiSecretKey was removed in 1.1.0 — the session/JWT signing key is now a
prerequisite opaque secret (encoding: plain) you create before install; set auth.secretKeyName to
its name instead

Create the secret with the key you already use

Store the same value your 1.0.0 release set in auth.webuiSecretKey as the payload of a new opaque secret. A different value signs every user out:

printf '%s' 'YOUR-EXISTING-WEBUI-SECRET-KEY' | cpln secret create-opaque --name SESSION_KEY_SECRET_NAME --encoding plain -f -

Update your values

Remove auth.webuiSecretKey and set auth.secretKeyName to the secret’s name. Then apply the changes from the later upgrade notes before you run the upgrade.

Upgrading from 1.1.0

Version 1.2.0 renamed the resource limits so it is unambiguous which number is the ceiling: resources.cpu is now resources.maxCpu and resources.memory is now resources.maxMemory. minCpu and minMemory are unchanged, and the shipped defaults are the same values.

An upgrade that still carries the old names is refused at render, leaving your running release untouched:

Error: ... open-webui: resources.cpu was RENAMED to resources.maxCpu. A block exposing both a
reservation and a limit names the limit maxCpu/maxMemory, so the bare name is no longer read and
would be silently ignored. Rename it in your values.

resources.memory produces the same message under its own name.

Rename the two keys in your values and upgrade. No data or account is affected.

Upgrading from 1.2.0

Version 1.3.0 creates the administrator from a secret, removes auth.enableSignup, makes the UI public by default, turns the Ollama backend off by default, and adds the Control Plane MCP tool server.

	1.2.0	1.3.0
Admin account	First account registered	`admin.secretName` → a dictionary secret you create
`auth.enableSignup`	Value, default `false`	Removed; manage sign-up in the UI
`publicAccess.enabled` default	`false`	`true`
`ollama.enabled` default	`true`	`false`
Control Plane MCP	—	`cplnMcp.enabled: true`

Create the admin secret first

1.3.0 requires admin.secretName, so create the dictionary secret before upgrading (see Prerequisites). An install that already has accounts ignores it and keeps every login. Put your current administrator’s email and password in it if you want the Control Plane tools added during the upgrade.

Update your values

Remove auth.enableSignup; the upgrade is refused while it is set. Manage sign-up in Settings → Admin → Authentication (New Sign Ups).
publicAccess.enabled now defaults to true, and your existing login protects it. Set it to false explicitly to stay private.
ollama.enabled now defaults to false. An existing install keeps its stored connections either way, because they are read on the first boot only.

Upgrade

Repeat the values you installed with; an upgrade only carries the values you pass it:

cpln helm upgrade RELEASE_NAME oci://ghcr.io/controlplane-com/templates/open-webui \
  --version 1.3.0 --gvc GVC_NAME \
  --set auth.secretKeyName=SESSION_KEY_SECRET_NAME \
  --set admin.secretName=ADMIN_SECRET_NAME

If the rollout stalls

The upgrade can stall for up to about 10 minutes while the platform grants access to the new admin secret. If RELEASE_NAME-open-webui has not moved to the new version after 5 minutes, force a redeployment:

cpln workload force-redeployment RELEASE_NAME-open-webui --gvc GVC_NAME

Carrying auth.enableSignup forward stops the upgrade, leaving your running release untouched:

Error: ... open-webui: auth.enableSignup was removed in 1.3.0 — the admin account is now created from
admin.secretName at first boot and sign-up is turned off then; open self-service sign-up from
Settings → Admin → Authentication (New Sign Ups) instead. Remove auth.enableSignup from your values.

The Control Plane tools are added on upgrade only when the admin secret holds your current administrator’s email and password. Otherwise add them by hand, as described in Connecting Control Plane Tools.

Scaling and Availability

The workload runs as exactly one replica by design, with no replicas value: the embedded SQLite database is single-writer and the volume set is per-replica, so a second instance would be a second, disconnected application rather than a cluster. A restart or upgrade is therefore a brief full outage of the UI. Scale vertically with resources, keeping the 4:1 maxCpu to minCpu ratio noted in Image and Resources. Multi-replica operation would need an external database, cache and object store, which this template does not offer.

Troubleshooting

Workload never becomes ready and cpln logs returns nothing

Symptom: cpln helm install reported success, the workload sits at zero ready replicas, and cpln logs returns zero lines. cpln workload get-deployments RELEASE_NAME-open-webui --gvc GVC_NAME -o yaml shows under status.versions[].message:

The secret SESSION_KEY_SECRET_NAME no longer exists. Workload updates are paused until the
secret is added or the reference to the secret removed.

Cause: auth.secretKeyName, admin.secretName or openai.apiKeySecretName names a secret that does not exist.Fix: Create the secret exactly as in Prerequisites. The workload recovers on its own after a wait, or run cpln workload force-redeployment RELEASE_NAME-open-webui --gvc GVC_NAME to skip it.

Upgrade from 1.2.0 does not move to the new version

Symptom: After cpln helm upgrade, RELEASE_NAME-open-webui stays on the old version.Cause: The platform is still granting the workload access to the new admin secret.Fix: After 5 minutes, run cpln workload force-redeployment RELEASE_NAME-open-webui --gvc GVC_NAME.

A user signs in and sees no models

Symptom: The administrator sees models, but a user you added sees an empty model picker.Cause: Models start private, so new users see none until you share them.Fix: In Settings → Admin → Models, open each model’s Access and make it Public, or grant it to users or groups.

The model picker is empty for everyone

Symptom: The UI loads and you can sign in, but no models are listed.Cause: No backend is configured (both are off by default), or ollama.workloadName does not name a ready Ollama workload in this GVC. An unreachable Ollama backend is non-fatal, so nothing else looks wrong.Fix: Confirm the backend is up, for Ollama with cpln workload get-deployments OLLAMA_WORKLOAD_NAME --gvc GVC_NAME -o yaml. Because backend values are read on the first boot only, add or correct a connection in Settings → Admin → Connections rather than by upgrading.

Control Plane tools fail or the chat errors once they are on

Symptom: With the Control Plane tools switched on, the model answers with an error instead of calling a tool.Cause: The model lacks tool calling, or its context is smaller than 64k tokens; the tool list alone is about 56k tokens.Fix: Use a model with tool calling and at least a 64k context. With vLLM, keep model.toolCallParser set and raise the context as in Connecting Control Plane Tools.

An image upload is rejected with is not a multimodal model

Symptom: Sending a screenshot or image fails with is not a multimodal model.Cause: The selected model is text-only.Fix: Use a vision model for image input.

A webhook or web page fetch to an address in the GVC is refused

Symptom: A webhook or web-page fetch to a *.cpln.local address fails.Cause: Open WebUI refuses private addresses for webhooks and web fetches. MCP tool servers are not affected.Fix: Expose the receiver publicly or use an external endpoint.

Changing ollama, openai or customDomain in an upgrade has no effect

Symptom: The upgrade succeeds, but the UI keeps its previous model connections or public URL.Cause: Those values are read from the environment only on the first boot; after that the stored setting wins.Fix: Change model connections in Settings → Admin → Connections. customDomain has to be set at the first install.

Custom domain hostname never resolves

Symptom: The install succeeded with customDomain set, but the hostname does not resolve and only the canonical endpoint works.Cause: customDomain sets WEBUI_URL only; it does not create a Control Plane domain.Fix: Create and verify the domain and its DNS records separately.

Every user was signed out at once

Symptom: All sessions became invalid at the same time, usually after a redeployment.Cause: The payload of the auth.secretKeyName secret changed, or the workload was pointed at a different secret. The key signs every session and JWT.Fix: Point auth.secretKeyName back at the original secret, or restore its original payload from your backup, then run cpln workload force-redeployment RELEASE_NAME-open-webui --gvc GVC_NAME. If the original key is lost, users simply sign in again; nothing else is affected.

Render error about auth.enableSignup or resources.cpu or auth.webuiSecretKey

Symptom: cpln helm upgrade fails before touching anything with auth.enableSignup was removed in 1.3.0, resources.cpu was RENAMED to resources.maxCpu or auth.webuiSecretKey was removed in 1.1.0.Cause: Your values still use keys from an earlier template version.Fix: Follow Upgrading from 1.2.0, Upgrading from 1.1.0 or Upgrading from 1.0.0.

Important Notes

Create both secrets before installing, and never change the session key. A missing secret wedges the deployment with no logs; the session key signs every session and JWT, so replacing it signs every user out.
The admin secret is read on the first boot only. Changing it later changes nothing; change the password in the UI (Settings → Account).
Self-service sign-up is off. Add users from Admin Panel → Users, or open sign-up in Settings → Admin → Authentication (New Sign Ups).
New users see no models until you share them. Set each model’s Access in Settings → Admin → Models.
ollama.*, openai.* and customDomain apply at install, then persist in the application database. A later upgrade is ignored and the old backend keeps working; change model connections in Settings → Admin → Connections.
The Control Plane tools need a model with tool calling and at least a 64k-token context. The tool list alone is about 56k tokens.
Image input needs a vision model. A text-only model rejects images with is not a multimodal model.
Webhooks and web-page fetches need a public URL. Open WebUI refuses private addresses such as *.cpln.local; MCP tool servers are not affected.
customDomain does not create a domain. It sets WEBUI_URL only; create the Control Plane domain and its DNS separately.
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. A restart or upgrade is a brief full outage of the UI.
Data lives only on the volume set. Uninstall deletes it (a final snapshot is taken first); a reinstall starts empty and creates the administrator from the admin secret again. Your own prerequisite secrets are not deleted, since the chart does not own them.
License / branding clause. Keep the “Open WebUI” branding visible in the UI unless your deployment serves 50 or fewer users or you have enterprise permission. It is not a template setting.

External References

Open WebUI on GitHub

Upstream source repository

Open WebUI Documentation

Official documentation and getting-started guides

Environment Variable Reference

Full list of supported configuration variables

License

The Open WebUI License and its branding clause

Ollama Template

Deploy the in-GVC Ollama model backend

vLLM Template

Serve an OpenAI-compatible model in the same GVC

Open WebUI Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Resources

Persistence and Backup

Authentication

Model Backends

Control Plane MCP

Access

Pairing with vLLM

Connecting

First Run

Connecting Control Plane Tools

Using a Model Backend

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.0

Upgrading from 1.1.0

Upgrading from 1.2.0

Scaling and Availability

Troubleshooting

Important Notes

External References

Open WebUI on GitHub

Open WebUI Documentation

Environment Variable Reference

License

Ollama Template

vLLM Template

Open WebUI Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Resources

​Persistence and Backup

​Authentication

​Model Backends

​Control Plane MCP

​Access

​Pairing with vLLM

​Connecting

​First Run

​Connecting Control Plane Tools

​Using a Model Backend

​Operations

​Backing Up

​Restoring a Backup

​Upgrading from 1.0.0

​Upgrading from 1.1.0

​Upgrading from 1.2.0

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

Open WebUI on GitHub

Open WebUI Documentation

Environment Variable Reference

License

Ollama Template

vLLM Template

Open WebUI Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Resources

Persistence and Backup

Authentication

Model Backends

Control Plane MCP

Access

Pairing with vLLM

Connecting

First Run

Connecting Control Plane Tools

Using a Model Backend

Operations

Backing Up

Restoring a Backup

Upgrading from 1.0.0

Upgrading from 1.1.0

Upgrading from 1.2.0

Scaling and Availability

Troubleshooting

Important Notes

External References