Skip to content
Open WebUI icon
v1.5.2App: v0.11.0Pinned DigestS3 Backup Ready

Production Helm chart • Apache-2.0 • Zero-Root • Verified on Kubernetes v1.33-v1.36+

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

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

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 Synced

Verified 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 .-> objectStore
Official Contractvalues.schema.json

Open WebUI Values Schema Reference

Official schema parameters, default values, and types extracted directly from the chart repository.

119 parametersValues Studio

Global(1)

ParameterTypeDefaultDescription
globalobject-Chart configuration parameter

Name Override(1)

ParameterTypeDefaultDescription
nameOverridestring""Chart configuration parameter

Fullname Override(1)

ParameterTypeDefaultDescription
fullnameOverridestring""Chart configuration parameter

Common Labels(1)

ParameterTypeDefaultDescription
commonLabelsobject-Chart configuration parameter

Image(3)

ParameterTypeDefaultDescription
image.repositorystring-Chart configuration parameter
image.tagstring-Chart configuration parameter
image.pullPolicystring-Chart configuration parameter
Allowed:AlwaysIfNotPresentNever

Image Pull Secrets(1)

ParameterTypeDefaultDescription
imagePullSecretsarray-Chart configuration parameter

Open Webui(11)

ParameterTypeDefaultDescription
openWebui.portinteger-Chart configuration parameter
openWebui.secretKeystring-Chart configuration parameter
openWebui.existingSecretstring-Chart configuration parameter
openWebui.existingSecretKeystring-Chart configuration parameter
openWebui.ollamaBaseUrlstring-Chart configuration parameter
openWebui.openaiBaseUrlstring-Chart configuration parameter
openWebui.openaiApiKeystring-Chart configuration parameter
openWebui.openaiExistingSecretstring-Chart configuration parameter
openWebui.openaiExistingSecretKeystring-Chart configuration parameter
openWebui.doNotTrackboolean-Chart configuration parameter
openWebui.extraEnvarray-Chart configuration parameter

Database(4)

ParameterTypeDefaultDescription
database.modestring-Chart configuration parameter
Allowed:autosqliteexternal
database.urlstring-Chart configuration parameter
database.existingSecretstring-Chart configuration parameter
database.existingSecretKeystring-Chart configuration parameter

Redis Config(4)

ParameterTypeDefaultDescription
redisConfig.modestring-Chart configuration parameter
Allowed:autoexternaldisabled
redisConfig.urlstring-Chart configuration parameter
redisConfig.existingSecretstring-Chart configuration parameter
redisConfig.existingSecretKeystring-Chart configuration parameter

Persistence(5)

ParameterTypeDefaultDescription
persistence.enabledboolean-Chart configuration parameter
persistence.sizestring-Chart configuration parameter
persistence.storageClassstring-Chart configuration parameter
persistence.accessModesarray-Chart configuration parameter
persistence.existingClaimstring-Chart configuration parameter

Service Account(4)

ParameterTypeDefaultDescription
serviceAccount.createboolean-Chart configuration parameter
serviceAccount.namestring-Chart configuration parameter
serviceAccount.annotationsobject-Chart configuration parameter
serviceAccount.automountServiceAccountTokenboolean-Chart configuration parameter

Service & Networking(3)

ParameterTypeDefaultDescription
service.typestring-Chart configuration parameter
Allowed:ClusterIPNodePortLoadBalancer
service.portinteger-Chart configuration parameter
service.annotationsobject-Chart configuration parameter

Network Policy(3)

ParameterTypeDefaultDescription
networkPolicy.enabledboolean-Chart configuration parameter
networkPolicy.ingressarray-Chart configuration parameter
networkPolicy.egressarray-Chart configuration parameter

Ingress(5)

ParameterTypeDefaultDescription
ingress.enabledboolean-Chart configuration parameter
ingress.ingressClassNamestring-Chart configuration parameter
ingress.annotationsobject-Chart configuration parameter
ingress.hostsarray-Chart configuration parameter
ingress.tlsarray-Chart configuration parameter

Health Probes(18)

ParameterTypeDefaultDescription
probes.startup.enabledboolean-Chart configuration parameter
probes.startup.pathstring-Chart configuration parameter
probes.startup.initialDelaySecondsinteger-Chart configuration parameter
probes.startup.periodSecondsinteger-Chart configuration parameter
probes.startup.timeoutSecondsinteger-Chart configuration parameter
probes.startup.failureThresholdinteger-Chart configuration parameter
probes.liveness.enabledboolean-Chart configuration parameter
probes.liveness.pathstring-Chart configuration parameter
probes.liveness.initialDelaySecondsinteger-Chart configuration parameter
probes.liveness.periodSecondsinteger-Chart configuration parameter
probes.liveness.timeoutSecondsinteger-Chart configuration parameter
probes.liveness.failureThresholdinteger-Chart configuration parameter
probes.readiness.enabledboolean-Chart configuration parameter
probes.readiness.pathstring-Chart configuration parameter
probes.readiness.initialDelaySecondsinteger-Chart configuration parameter
probes.readiness.periodSecondsinteger-Chart configuration parameter
probes.readiness.timeoutSecondsinteger-Chart configuration parameter
probes.readiness.failureThresholdinteger-Chart configuration parameter

Resources(1)

ParameterTypeDefaultDescription
resourcesobject-Chart configuration parameter

Pod Security(1)

ParameterTypeDefaultDescription
podSecurityContext.seccompProfile.typestring-Chart configuration parameter

Container Security(2)

ParameterTypeDefaultDescription
securityContext.allowPrivilegeEscalationboolean-Chart configuration parameter
securityContext.capabilities.droparray-Chart configuration parameter

Backup(27)

ParameterTypeDefaultDescription
backup.enabledboolean-Chart configuration parameter
backup.schedulestring-Chart configuration parameter
backup.suspendboolean-Chart configuration parameter
backup.concurrencyPolicystring-Chart configuration parameter
Allowed:AllowForbidReplace
backup.successfulJobsHistoryLimitinteger-Chart configuration parameter
backup.failedJobsHistoryLimitinteger-Chart configuration parameter
backup.backoffLimitinteger-Chart configuration parameter
backup.archivePrefixstring-Chart configuration parameter
backup.images.postgresqlstring-Chart configuration parameter
backup.images.uploaderstring-Chart configuration parameter
backup.resourcesobject-Chart configuration parameter
backup.database.pgDumpArgsstring-Chart configuration parameter
backup.database.hoststring-Chart configuration parameter
backup.database.portinteger-Chart configuration parameter
backup.database.namestring-Chart configuration parameter
backup.database.usernamestring-Chart configuration parameter
backup.database.existingSecretstring-Chart configuration parameter
backup.database.existingSecretKeystring-Chart configuration parameter
backup.s3.endpointstring-Chart configuration parameter
backup.s3.bucketstring-Chart configuration parameter
backup.s3.prefixstring-Chart configuration parameter
backup.s3.createBucketIfNotExistsboolean-Chart configuration parameter
backup.s3.existingSecretstring-Chart configuration parameter
backup.s3.existingSecretAccessKeyKeystring-Chart configuration parameter
backup.s3.existingSecretSecretKeyKeystring-Chart configuration parameter
backup.s3.accessKeystring-Chart configuration parameter
backup.s3.secretKeystring-Chart configuration parameter

Node Selector(1)

ParameterTypeDefaultDescription
nodeSelectorobject-Chart configuration parameter

Tolerations(1)

ParameterTypeDefaultDescription
tolerationsarray-Chart configuration parameter

Affinity(1)

ParameterTypeDefaultDescription
affinityobject-Chart configuration parameter

Topology Spread Constraints(1)

ParameterTypeDefaultDescription
topologySpreadConstraintsarray-Chart configuration parameter

Priority Class Name(1)

ParameterTypeDefaultDescription
priorityClassNamestring-Chart configuration parameter

Termination Grace Period Seconds(1)

ParameterTypeDefaultDescription
terminationGracePeriodSecondsinteger-Chart configuration parameter

Pod Labels(1)

ParameterTypeDefaultDescription
podLabelsobject-Chart configuration parameter

Pod Annotations(1)

ParameterTypeDefaultDescription
podAnnotationsobject-Chart configuration parameter

Extra Volumes(1)

ParameterTypeDefaultDescription
extraVolumesarray-Chart configuration parameter

Extra Volume Mounts(1)

ParameterTypeDefaultDescription
extraVolumeMountsarray-Chart configuration parameter

Extra Manifests(1)

ParameterTypeDefaultDescription
extraManifestsarray-Chart configuration parameter

Postgresql(7)

ParameterTypeDefaultDescription
postgresql.enabledboolean-Chart configuration parameter
postgresql.architecturestring-Chart configuration parameter
postgresql.auth.databasestring-Chart configuration parameter
postgresql.auth.usernamestring-Chart configuration parameter
postgresql.auth.passwordstring-Chart configuration parameter
postgresql.primary.persistence.enabledboolean-Chart configuration parameter
postgresql.primary.persistence.sizestring-Chart configuration parameter

Redis(5)

ParameterTypeDefaultDescription
redis.enabledboolean-Chart configuration parameter
redis.architecturestring-Chart configuration parameter
redis.auth.enabledboolean-Chart configuration parameter
redis.auth.passwordstring-Chart configuration parameter
redis.master.persistence.enabledboolean-Chart configuration parameter