Helm Charts and Deployment¶
Helm Chart Details¶
OpenWebUI is deployed on each K3s cluster using the official Helm chart:
| Property | Value |
|---|---|
| Chart repository | open-webui/open-webui |
| Chart version | v13.3.1 |
| Application version | v0.8.12 |
| Namespace | open-webui |
| Service type | NodePort (port 30080) |
Helm is the standard package manager for Kubernetes. It allows complex applications to be installed, configured, and upgraded using declarative YAML values files. Each of the three Astra clusters has its own independent Helm release.
Key Helm Values¶
The following values are configured in the Helm release for each cluster. These control the behavior of the OpenWebUI deployment.
Database Connection¶
Each cluster's DATABASE_URL points to its own node1's IP address on port 5432:
Database connectivity note
In the current ground-based prototype, the DATABASE_URL uses stable overlay network IPs that provide cross-network reachability during development. If the pod runs on node2 (agent), it can still reach node1's PostgreSQL regardless of the underlying physical network topology. In a flight deployment, standard LAN IPs would be used since all devices are on the same physical network.
Session Secret Key¶
All three clusters share the same WEBUI_SECRET_KEY. This is critical for failover: session cookies generated by one cluster must be valid on any other cluster. If the keys differed, users would be forced to log in again after every failover event.
Offline Operation Flags¶
These environment variables prevent the HuggingFace Hub and Transformers Python libraries from attempting network downloads at startup. Without these flags, the libraries try to check for updated model weights and tokenizers on every pod start. In an offline environment, these requests either hang indefinitely or crash the application.
All required model files are pre-cached locally at /opt/owui-cache/ on every node1.
Database Migration Workaround¶
Known bug in OpenWebUI v0.8.12
OpenWebUI v0.8.12 has a bug in its db.py module where a # db = None line is commented out. This causes the peewee ORM migration system to crash on startup. Setting ENABLE_DB_MIGRATIONS=False safely bypasses the migration check. The database schema is already correct from the initial setup, so no migrations are needed.
Ollama Backend¶
This enables the Ollama integration in OpenWebUI, allowing users to interact with locally-hosted AI models served by the three AI backend servers.
Vector Database¶
OpenWebUI uses PostgreSQL with the pgvector extension for storing and querying embedding vectors. This enables RAG (Retrieval-Augmented Generation) functionality, where uploaded documents are converted to vector embeddings and stored in the same PostgreSQL database that holds all other application data.
WebSocket Support¶
WebSocket support is disabled because it requires a Redis backend for cross-pod message passing. Since Astra runs a single OpenWebUI pod per cluster and does not use Redis, WebSocket support is unnecessary.
Complete Environment Variable Reference¶
| Variable | Value | Purpose |
|---|---|---|
DATABASE_URL |
postgresql://openwebui:...@<node1-ip>:5432/openwebui |
Per-cluster database connection string |
WEBUI_SECRET_KEY |
(shared across all clusters) | Session cookie signing key for failover compatibility |
ENABLE_DB_MIGRATIONS |
False |
Bypass peewee migration bug in v0.8.12 |
HF_HUB_OFFLINE |
1 |
Prevent HuggingFace library network downloads |
TRANSFORMERS_OFFLINE |
1 |
Prevent Transformers library network downloads |
ENABLE_OLLAMA_API |
True |
Enable local Ollama AI model backend |
VECTOR_DB |
pgvector |
Use PostgreSQL pgvector for embedding storage |
ENABLE_WEBSOCKET_SUPPORT |
False |
Disabled (no Redis backend) |
Ollama Base URL Configuration¶
Ollama URLs are stored in the database, not in Helm values
The Ollama base URLs (the addresses of the three AI servers) are not configured as Kubernetes environment variables. They are stored in the OpenWebUI PostgreSQL config table and loaded by the application on startup.
The current Ollama base URLs use LAN IPs for fully offline operation:
| AI Server | LAN IP | Ollama URL | Prefix ID |
|---|---|---|---|
| ai-server3 (Jetson GPU) | 10.0.0.43 | http://10.0.0.43:11434 |
ai3 |
| ai-server1 (Pi 5 CPU) | 10.0.0.41 | http://10.0.0.41:11434 |
ai1 |
| ai-server2 (Pi 5 CPU) | 10.0.0.42 | http://10.0.0.42:11434 |
ai2 |
Because these URLs are stored in the replicated PostgreSQL database, they are automatically consistent across all three clusters. A configuration change on one cluster propagates to the others via streaming replication.
To update the Ollama configuration, use the OpenWebUI API endpoint:
This endpoint requires admin authentication.
Pre-Cached Embedding Models¶
OpenWebUI uses sentence transformer models to generate vector embeddings for RAG functionality. These models are pre-cached on all three node1s to support offline operation.
| Property | Value |
|---|---|
| Cache location | /opt/owui-cache/ |
| Cache size | 924 MB |
| Mount type | Kubernetes hostPath volume (read-only) |
The cache directory is mounted into the OpenWebUI pod as a hostPath volume. The HuggingFace and Transformers libraries read from this cache instead of downloading from the internet (enforced by the HF_HUB_OFFLINE=1 and TRANSFORMERS_OFFLINE=1 flags).
Container Image Caching¶
All required container images are pre-cached on every node in the system. This is essential for offline operation -- without cached images, K3s would attempt to pull images from container registries on the internet, which is not available during demo operation.
Pre-cached images include:
- OpenWebUI application image
- K3s system images (CoreDNS, metrics server, etc.)
Verify image availability before demo day
To confirm that all required images are available on a node:
Then verify each image exists in the local containerd image store:How to Update or Redeploy¶
Upgrading OpenWebUI¶
To upgrade the OpenWebUI Helm release on a cluster:
# Update the Helm chart repository
helm repo update open-webui
# Upgrade the release with existing values
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml helm upgrade open-webui open-webui/open-webui \
-n open-webui \
-f values.yaml
Upgrade on the primary cluster first
Always upgrade the primary cluster (the one holding the VIP) first. The upgrade may trigger database migrations that must run against a writable database. Standby clusters have read-only databases and will fail migrations.
Restarting the OpenWebUI Pod¶
To force a pod restart without changing the configuration:
sudo KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl delete pod \
-n open-webui \
-l app.kubernetes.io/name=open-webui
K3s automatically creates a replacement pod within seconds.
Viewing Current Configuration¶
To inspect the current Helm values for a deployment:
To see all values (including defaults):