From 39717dc5e5b7836b49a7bbd66fb196eb031bd37e Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Tue, 23 Dec 2025 11:25:03 +0100 Subject: [PATCH] new env var --- docs/getting-started/env-configuration.mdx | 21 +++++++++++++++----- docs/getting-started/updating.mdx | 5 ++++- docs/troubleshooting/multi-replica.mdx | 23 ++++++++++++++++------ 3 files changed, 37 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index f92c3675..af273487 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -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` diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 8e375be1..c87a24b0 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -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. ::: ::: diff --git a/docs/troubleshooting/multi-replica.mdx b/docs/troubleshooting/multi-replica.mdx index 052e34c4..d6879faf 100644 --- a/docs/troubleshooting/multi-replica.mdx +++ b/docs/troubleshooting/multi-replica.mdx @@ -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.