Open WebUI Helm chart
Open WebUI is a self-hosted AI interface for Ollama and OpenAI-compatible model providers. This chart deploys a single Open WebUI instance with persistent data, optional PostgreSQL and Redis dependencies, ingress, and PostgreSQL backups.
Features
- SQLite evaluation mode or PostgreSQL for production data.
- Bundled or external PostgreSQL and Redis integrations.
- Secret-backed application, provider, database, Redis, and S3 credentials.
- HTTP startup, liveness, and database-aware readiness probes.
- S3-compatible PostgreSQL backup CronJob.
- Dedicated tokenless ServiceAccount and ingress-isolating NetworkPolicy.
- Recreate upgrades to prevent concurrent migrations and SQLite access.
- Strict values schema and fail-fast validation for incompatible modes.
Architecture
One web Deployment exposes a named HTTP port through a Service. The Service
selects only web component pods, while backup Jobs use a separate component
label. The data PVC stores SQLite, uploads, and embedding assets. Optional
PostgreSQL and Redis dependencies provide production data and WebSocket paths.
The design document explains why the chart remains single-replica.
Installation
Install from the signed OCI registry:
helm install open-webui oci://ghcr.io/helmforgedev/helm/open-webui \
--namespace open-webui \
--create-namespace
Wait for the initial embedding-model download and application startup:
kubectl wait --namespace open-webui \
--for=condition=Available deployment/open-webui-open-webui \
--timeout=15m
kubectl port-forward --namespace open-webui \
service/open-webui-open-webui 8080:80
Open http://localhost:8080 and create the initial administrator account.
Configuration
Model providers
Connect Ollama:
openWebui:
ollamaBaseUrl: http://ollama.ollama.svc.cluster.local:11434
Connect an OpenAI-compatible endpoint. Prefer a pre-created Secret:
kubectl create secret generic openai-credentials \
--namespace open-webui \
--from-literal=openai-api-key='replace-me'
openWebui:
openaiBaseUrl: https://api.openai.com/v1
openaiExistingSecret: openai-credentials
openaiExistingSecretKey: openai-api-key
An endpoint that does not require authentication may set only
openWebui.openaiBaseUrl; the chart does not create a dangling API-key
reference.
Database modes
| Mode | Configuration | Intended use |
|---|---|---|
| SQLite | database.mode: auto with PostgreSQL disabled |
Evaluation and small single-user installs on local storage |
| Bundled PostgreSQL | postgresql.enabled: true |
Convenient production starting point |
| External PostgreSQL | database.mode: external |
Operator-managed production database |
Bundled PostgreSQL:
postgresql:
enabled: true
auth:
database: openwebui
username: openwebui
External PostgreSQL with a Secret containing the full connection URL:
kubectl create secret generic open-webui-database \
--namespace open-webui \
--from-literal=database-url='postgresql://openwebui:[email protected]:5432/openwebui'
database:
mode: external
existingSecret: open-webui-database
existingSecretKey: database-url
SQLite must not use NFS, SMB, CephFS, Azure Files, or another network-backed volume. Use PostgreSQL when the storage is not directly attached local SSD/NVMe.
Redis and WebSockets
Redis is optional for the supported single-replica topology. Enable the bundled dependency when preparing integrations that rely on Redis:
redis:
enabled: true
For an external Redis instance, provide the complete URL through a Secret:
redisConfig:
mode: external
existingSecret: open-webui-redis
existingSecretKey: redis-url
The chart configures both REDIS_URL and WEBSOCKET_REDIS_URL and enables the
Redis WebSocket manager when Redis is active.
Ingress
ingress:
enabled: true
ingressClassName: nginx
hosts:
- host: chat.example.com
paths:
- path: /
pathType: Prefix
tls:
- hosts:
- chat.example.com
secretName: open-webui-tls
Enabling ingress without at least one host fails during rendering.
PostgreSQL backups
The backup job streams pg_dump output to S3-compatible storage. Use an
existing Secret for object-storage credentials:
postgresql:
enabled: true
backup:
enabled: true
schedule: "0 3 * * *"
s3:
endpoint: https://s3.example.com
bucket: open-webui-backups
existingSecret: open-webui-s3
existingSecretAccessKeyKey: access-key
existingSecretSecretKeyKey: secret-key
External PostgreSQL backups additionally require backup.database.host,
port, name, username, and a Secret containing only the database password.
See the configuration guide.
Key values
| Value | Default | Description |
|---|---|---|
image.repository |
ghcr.io/open-webui/open-webui |
Official application image |
image.tag |
v0.11.0 |
Pinned application image tag |
openWebui.port |
8080 |
Application listener and container port |
openWebui.ollamaBaseUrl |
"" |
Ollama API URL |
database.mode |
auto |
SQLite, bundled PostgreSQL, or external PostgreSQL selection |
redisConfig.mode |
auto |
Bundled, external, or disabled Redis selection |
persistence.enabled |
true |
Persist /app/backend/data |
persistence.size |
10Gi |
Data PVC request |
service.port |
80 |
Kubernetes Service port |
networkPolicy.enabled |
true |
Isolate inbound application traffic |
backup.enabled |
false |
Schedule PostgreSQL backups |
See values.yaml for the complete contract and
examples/production.yaml for a production-oriented
starting point.
Examples
examples/postgresql-multiuser.yamlenables PostgreSQL and Redis with measured resource placeholders.examples/production.yamladds existing Secrets, TLS ingress, larger persistence, backup, and NetworkPolicy guidance.
Security
The chart creates a dedicated ServiceAccount without an API token, enables
RuntimeDefault seccomp, disables privilege escalation, drops Linux
capabilities, and restricts inbound traffic to the named HTTP port. Egress is
open because model endpoints and identity providers are operator-selected; set
networkPolicy.egress to an environment-specific allowlist where possible.
The official image runs as UID 0 and needs writable application and home paths.
Consequently, the chart does not claim runAsNonRoot or a read-only root
filesystem by default. This exception and its operational consequences are
documented in the security guide.
Avoid inline production credentials. Existing Secrets keep credentials out of rendered workload specs, but Helm values and Kubernetes Secret access still need strict RBAC. Terminate TLS at the ingress and protect the initial administrator enrollment path.
Operations
The first startup can take several minutes while Open WebUI downloads its RAG
embedding model. The startup probe allows approximately ten minutes. Readiness
uses /health/db, while startup and liveness use /health.
Read the operations guide before upgrades. It covers backup verification, restore drills, probe diagnosis, database connectivity, Redis connectivity, and the deliberate single-replica boundary.
Troubleshooting
Start with pod events, logs, Service endpoints, and both health routes:
kubectl describe pod --namespace open-webui \
--selector app.kubernetes.io/name=open-webui
kubectl logs --namespace open-webui \
deployment/open-webui-open-webui --tail=100
kubectl get endpointslice --namespace open-webui
Use the symptom-based procedures in the operations guide for startup downloads, database readiness, Redis WebSockets, PVC binding, and backup failures.
Upgrade notes
- Back up PostgreSQL or the full data PVC before upgrading.
- The Deployment uses
Recreate, causing brief downtime while protecting SQLite and migration integrity. - PostgreSQL and Redis subcharts are independent stateful dependencies; review their release notes before dependency-major upgrades.
- Do not run mixed Open WebUI versions against one database.
Documentation
- Chart design and boundaries
- Configuration reference
- Operations and recovery
- Security model
- PostgreSQL multi-user example
- Production example
- Open WebUI documentation
Security Scan: open-webui
| Framework | Score |
|---|---|
| MITRE + NSA + SOC2 | 79.29293% |
Security posture acceptable. The score is refreshed by CI from the rendered manifests and does not replace application-image vulnerability scanning.
System Architecture
DESIGN.md SyncedVerified architecture contract rendered dynamically from GitHub DESIGN.md
flowchart LR
client[Browser or API client]
gateway[Ingress or Gateway API]
service[Open WebUI Service]
subgraph application[Open WebUI application]
wait[Database wait init container: auto mode only]
web[Open WebUI Deployment]
data[Application data PVC]
backup[Optional PostgreSQL backup CronJob]
end
subgraph services[Data and integration boundary]
sqlite[SQLite on the application data PVC]
bundledPostgresql[Bundled PostgreSQL]
externalPostgresql[External PostgreSQL]
bundledRedis[Bundled Redis]
externalRedis[External Redis]
redisDisabled[Disabled mode: no Redis connection]
models[Ollama or OpenAI-compatible APIs]
objectStore[S3-compatible object storage]
end
client -. ingress or Gateway enabled .-> gateway --> service --> web
wait -. auto mode only .-> bundledPostgresql
web --> data
web -. sqlite mode or auto without subchart .-> sqlite
web -. auto mode with subchart .-> bundledPostgresql
web -. external mode .-> externalPostgresql
web -. Redis auto mode .-> bundledRedis
web -. Redis external mode .-> externalRedis
web --> models
backup -. bundled PostgreSQL backup .-> bundledPostgresql
backup -. external PostgreSQL backup .-> externalPostgresql
backup -. backup enabled .-> objectStoreOpen WebUI Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Chart configuration parameter |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Open Webui(11)
| Parameter | Type | Default | Description |
|---|---|---|---|
| openWebui.port | integer | - | Chart configuration parameter |
| openWebui.secretKey | string | - | Chart configuration parameter |
| openWebui.existingSecret | string | - | Chart configuration parameter |
| openWebui.existingSecretKey | string | - | Chart configuration parameter |
| openWebui.ollamaBaseUrl | string | - | Chart configuration parameter |
| openWebui.openaiBaseUrl | string | - | Chart configuration parameter |
| openWebui.openaiApiKey | string | - | Chart configuration parameter |
| openWebui.openaiExistingSecret | string | - | Chart configuration parameter |
| openWebui.openaiExistingSecretKey | string | - | Chart configuration parameter |
| openWebui.doNotTrack | boolean | - | Chart configuration parameter |
| openWebui.extraEnv | array | - | Chart configuration parameter |
Database(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| database.mode | string | - | Chart configuration parameter Allowed: autosqliteexternal |
| database.url | string | - | Chart configuration parameter |
| database.existingSecret | string | - | Chart configuration parameter |
| database.existingSecretKey | string | - | Chart configuration parameter |
Redis Config(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| redisConfig.mode | string | - | Chart configuration parameter Allowed: autoexternaldisabled |
| redisConfig.url | string | - | Chart configuration parameter |
| redisConfig.existingSecret | string | - | Chart configuration parameter |
| redisConfig.existingSecretKey | string | - | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Chart configuration parameter |
| persistence.size | string | - | Chart configuration parameter |
| persistence.storageClass | string | - | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
Network Policy(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.ingress | array | - | Chart configuration parameter |
| networkPolicy.egress | array | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Health Probes(18)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup.enabled | boolean | - | Chart configuration parameter |
| probes.startup.path | string | - | Chart configuration parameter |
| probes.startup.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.startup.periodSeconds | integer | - | Chart configuration parameter |
| probes.startup.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.startup.failureThreshold | integer | - | Chart configuration parameter |
| probes.liveness.enabled | boolean | - | Chart configuration parameter |
| probes.liveness.path | string | - | Chart configuration parameter |
| probes.liveness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.liveness.periodSeconds | integer | - | Chart configuration parameter |
| probes.liveness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.liveness.failureThreshold | integer | - | Chart configuration parameter |
| probes.readiness.enabled | boolean | - | Chart configuration parameter |
| probes.readiness.path | string | - | Chart configuration parameter |
| probes.readiness.initialDelaySeconds | integer | - | Chart configuration parameter |
| probes.readiness.periodSeconds | integer | - | Chart configuration parameter |
| probes.readiness.timeoutSeconds | integer | - | Chart configuration parameter |
| probes.readiness.failureThreshold | integer | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter |
Container Security(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
Backup(27)
| Parameter | Type | Default | Description |
|---|---|---|---|
| backup.enabled | boolean | - | Chart configuration parameter |
| backup.schedule | string | - | Chart configuration parameter |
| backup.suspend | boolean | - | Chart configuration parameter |
| backup.concurrencyPolicy | string | - | Chart configuration parameter Allowed: AllowForbidReplace |
| backup.successfulJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.failedJobsHistoryLimit | integer | - | Chart configuration parameter |
| backup.backoffLimit | integer | - | Chart configuration parameter |
| backup.archivePrefix | string | - | Chart configuration parameter |
| backup.images.postgresql | string | - | Chart configuration parameter |
| backup.images.uploader | string | - | Chart configuration parameter |
| backup.resources | object | - | Chart configuration parameter |
| backup.database.pgDumpArgs | string | - | Chart configuration parameter |
| backup.database.host | string | - | Chart configuration parameter |
| backup.database.port | integer | - | Chart configuration parameter |
| backup.database.name | string | - | Chart configuration parameter |
| backup.database.username | string | - | Chart configuration parameter |
| backup.database.existingSecret | string | - | Chart configuration parameter |
| backup.database.existingSecretKey | string | - | Chart configuration parameter |
| backup.s3.endpoint | string | - | Chart configuration parameter |
| backup.s3.bucket | string | - | Chart configuration parameter |
| backup.s3.prefix | string | - | Chart configuration parameter |
| backup.s3.createBucketIfNotExists | boolean | - | Chart configuration parameter |
| backup.s3.existingSecret | string | - | Chart configuration parameter |
| backup.s3.existingSecretAccessKeyKey | string | - | Chart configuration parameter |
| backup.s3.existingSecretSecretKeyKey | string | - | Chart configuration parameter |
| backup.s3.accessKey | string | - | Chart configuration parameter |
| backup.s3.secretKey | string | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
Postgresql(7)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | - | Chart configuration parameter |
| postgresql.architecture | string | - | Chart configuration parameter |
| postgresql.auth.database | string | - | Chart configuration parameter |
| postgresql.auth.username | string | - | Chart configuration parameter |
| postgresql.auth.password | string | - | Chart configuration parameter |
| postgresql.primary.persistence.enabled | boolean | - | Chart configuration parameter |
| postgresql.primary.persistence.size | string | - | Chart configuration parameter |
Redis(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| redis.enabled | boolean | - | Chart configuration parameter |
| redis.architecture | string | - | Chart configuration parameter |
| redis.auth.enabled | boolean | - | Chart configuration parameter |
| redis.auth.password | string | - | Chart configuration parameter |
| redis.master.persistence.enabled | boolean | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.