c270f4b934
ChromaDB's default local PersistentClient uses SQLite which is not fork-safe. When uvicorn forks multiple workers, concurrent writes crash workers instantly. Added warnings and guidance across env config, HA/scaling, performance, troubleshooting, Docker Swarm, Helm, Redis, RAG, and enterprise architecture docs. https://claude.ai/code/session_01TPoquFdHG6dZxRrZ4Jormh
3.2 KiB
Helm Setup for Kubernetes
Helm helps you manage Kubernetes applications.
Prerequisites
- Kubernetes cluster is set up.
- Helm is installed.
Helm Steps
-
Add Open WebUI Helm Repository:
helm repo add open-webui https://open-webui.github.io/helm-charts helm repo update -
Install Open WebUI Chart:
helm install openwebui open-webui/open-webui -
Verify Installation:
kubectl get pods
:::warning
If you intend to scale Open WebUI using multiple nodes/pods/workers in a clustered environment, you need to setup a NoSQL key-value database (Redis). There are some environment variables that need to be set to the same value for all service-instances, otherwise consistency problems, faulty sessions and other issues will occur!
Important: The default vector database (ChromaDB) uses a local SQLite-backed client that is not safe for multi-replica or multi-worker deployments. SQLite connections are not fork-safe, and concurrent writes from multiple processes will crash workers instantly. You must switch to an external vector database (PGVector, Milvus, Qdrant) via VECTOR_DB, or run ChromaDB as a separate HTTP server via CHROMA_HTTP_HOST. See the Scaling & HA guide for full requirements.
:::
:::danger Critical for Updates
If you run Open WebUI with multiple replicas/pods (replicaCount > 1) or UVICORN_WORKERS > 1, you MUST scale down to a single replica/pod during updates.
- Scale down deployment to 1 replica.
- Apply the update (new image version).
- Wait for the pod to be fully ready (database migrations complete).
- Scale back up to your desired replica count.
Failure to do this can result in database corruption due to concurrent migrations. :::
Access the WebUI
You can access Open WebUI by port-forwarding or configuring an Ingress.
Ingress Configuration (Nginx)
If you are using the NGINX Ingress Controller, you can enable session affinity (sticky sessions) to improve WebSocket stability. Add the following annotation to your Ingress resource:
metadata:
annotations:
nginx.ingress.kubernetes.io/affinity: "cookie"
nginx.ingress.kubernetes.io/session-cookie-name: "open-webui-session"
nginx.ingress.kubernetes.io/session-cookie-expires: "172800"
nginx.ingress.kubernetes.io/session-cookie-max-age: "172800"
This ensures that a user's session remains connected to the same pod, reducing issues with WebSocket connections in multi-replica setups (though correct Redis configuration makes this less critical).
Uninstall
-
Uninstall the Helm Release:
helm uninstall openwebui -
Remove Persistent Volume Claims (WARNING: Deletes all data): Helm does not automatically delete PVCs to prevent accidental data loss. You must delete them manually if you want to wipe everything.
kubectl delete pvc -l app.kubernetes.io/instance=openwebui