khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2026-01-03 02:09:51 +07:00
Code Issues Packages Projects Releases Wiki Activity

new env var

Browse Source
This commit is contained in:
DrMelone
2025-12-23 11:25:03 +01:00
parent 386696c244
commit 39717dc5e5
3 changed files with 37 additions and 12 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
docs/getting-started/env-configuration.mdx
View File

@@ -5049,6 +5049,12 @@ For configuration using individual parameters or encrypted SQLite, see the relev
:::
#### `ENABLE_DB_MIGRATIONS`
- Type: `bool`
- Default: `True`
- Description: Controls whether database migrations are automatically run on startup. In multi-pod or multi-worker deployments, set this to `False` on all pods except one to designate a "master" pod responsible for migrations, preventing race conditions or schema corruption.
:::warning
**Required for Multi-Replica Setups**
@@ -5056,6 +5062,8 @@ For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), y
:::
#### `DATABASE_TYPE`
- Type: `str`
@@ -5469,16 +5477,19 @@ If you use UVICORN_WORKERS, you also need to ensure that related environment var
:::
:::warning Database Migrations with Multiple Workers
When `UVICORN_WORKERS > 1`, starting the application can trigger concurrent database migrations from multiple worker processes, potentially causing database schema corruption or inconsistent states.
:::warning Database Migrations with Multiple Workers / Multi-Pod Deployments
When `UVICORN_WORKERS > 1` or when running multiple replicas, starting the application can trigger concurrent database migrations from multiple processes, potentially causing database schema corruption or inconsistent states.
**Recommendation:**
After pulling a new image or installing an update, **always run Open WebUI with a single worker (`UVICORN_WORKERS=1`) first**. This ensures the database migration completes successfully in a single process. Once the migration is finished and the application has started, you can then restart it with your desired number of workers.
To handle migrations safely in multi-process/multi-pod environments, you can:
1. **Designate a Master (Recommended):** Set `ENABLE_DB_MIGRATIONS=False` on all but one instance/worker. The instance with `ENABLE_DB_MIGRATIONS=True` (default) will handle the migration, while others will wait or skip it.
2. **Scale Down:** Temporarily scale down to a single instance/worker to let migrations finish before scaling back up.
**For Kubernetes, Helm, Minikube, and other orchestrated setups:**
Ensure that your deployment strategy allows for a single-replica or single-worker init container/job to handle migrations before scaling up to multiple replicas or workers. This is critical to prevent race conditions during schema updates.
**For Kubernetes, Helm, and Orchestrated Setups:**
It is recommended to use the `ENABLE_DB_MIGRATIONS` variable to designate a specific pod for migrations, or use an init container/job to handle migrations before scaling up the main application pods. This ensures schema updates are applied exactly once.
:::
### Cache Settings
#### `CACHE_CONTROL`

5
docs/getting-started/updating.mdx
View File

@@ -14,7 +14,10 @@ Keeping Open WebUI updated ensures you have the latest features, security patche
- **Backup your data** before major version updates
- **Check release notes** at https://github.com/open-webui/open-webui/releases for breaking changes
- **Clear browser cache** after updating to ensure the latest web interface loads
- **Running Multiple Workers?** If you use `UVICORN_WORKERS > 1`, you **MUST** run the updated container with `UVICORN_WORKERS=1` first to perform database migrations safely. Once started successfully, you can restart with multiple workers.
- **Running Multiple Workers?** If you use `UVICORN_WORKERS > 1`, you **MUST** ensure migrations run safely by either:
1. Running the updated container with `UVICORN_WORKERS=1` first.
2. Designating a master worker using `ENABLE_DB_MIGRATIONS=True` (default) on one instance and `False` on others.
Once migrations complete, you can run with multiple workers normally.
:::
:::

23
docs/troubleshooting/multi-replica.mdx
View File

@@ -123,16 +123,27 @@ The `/app/backend/data` directory is not shared or is not consistent across repl
### Updates and Migrations
:::danger Critical: Avoid Concurrent Migrations
**Always scale down to 1 replica (and 1 worker) before upgrading Open WebUI versions.**
**Always ensure only one process is running database migrations when upgrading Open WebUI versions.**
:::
Database migrations run automatically on startup. If multiple replicas (or multiple workers within a single container) start simultaneously with a new version, they may try to run migrations concurrently, leading to race conditions or database schema corruption.
Database migrations run automatically on startup. If multiple replicas (or multiple workers within a single container) start simultaneously with a new version, they may try to run migrations concurrently, potentially leading to race conditions or database schema corruption.
**Safe Update Procedure:**
1. **Scale Down:** Set replicas to `1` (and ensure `UVICORN_WORKERS=1` if you customized it).
2. **Update Image:** Application restarts with the new version.
3. **Wait for Health Check:** Ensure the single instance starts up fully and completes DB migrations.
4. **Scale Up:** Increase replicas (or `UVICORN_WORKERS`) back to your desired count.
There are two ways to safely handle migrations in a multi-replica environment:
#### Option 1: Designate a Master Migration Pod (Recommended)
1. Identify one pod/replica as the "master" for migrations.
2. Set `ENABLE_DB_MIGRATIONS=True` (default) on the master pod.
3. Set `ENABLE_DB_MIGRATIONS=False` on all other pods.
4. When updating, the master pod will handle the database schema update while other pods skip the migration step.
#### Option 2: Scale Down During Update
1. **Scale Down:** Set replicas to `1` (and ensure `UVICORN_WORKERS=1`).
2. **Update Image:** Update the image or version.
3. **Wait for Health Check:** Wait for the single instance to start fully and complete migrations.
4. **Scale Up:** Increase replicas back to your desired count.
### Session Affinity (Sticky Sessions)
While Open WebUI is designed to be stateless with proper Redis configuration, enabling **Session Affinity** (Sticky Sessions) at your Load Balancer / Ingress level can improve performance and reduce occasional jitter in WebSocket connections.