From 43ae2b98df4dce92c171dc1dc3aa97dd5967f0c2 Mon Sep 17 00:00:00 2001 From: Hendrik Hassa <65833107+HennieLP@users.noreply.github.com> Date: Tue, 2 Dec 2025 18:31:08 +0100 Subject: [PATCH 01/12] Adds document intelligence model configuration Adds the `DOCUMENT_INTELLIGENCE_MODEL` environment variable, allowing users to specify the model used for document intelligence. --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5dec0df04..475ba8390 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2639,6 +2639,13 @@ Strictly return in JSON format: - Description: Specifies the key for document intelligence. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `DOCUMENT_INTELLIGENCE_MODEL` + +- Type: `str` +- Default: `None` +- Description: Specifies the model for document intelligence. +- Persistence: This environment variable is a `PersistentConfig` variable. + ### Advanced Settings #### `BYPASS_EMBEDDING_AND_RETRIEVAL` From fbd240c0d4cc1d6e7f61e3a2acab625cb5d08886 Mon Sep 17 00:00:00 2001 From: bitsofinfo Date: Thu, 4 Dec 2025 15:02:57 -0700 Subject: [PATCH 02/12] feat: AUTH0_AUDIENCE --- docs/features/auth/sso/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/features/auth/sso/index.mdx b/docs/features/auth/sso/index.mdx index 72395c775..6965d8d04 100644 --- a/docs/features/auth/sso/index.mdx +++ b/docs/features/auth/sso/index.mdx @@ -121,6 +121,10 @@ The following environment variables are used: 1. `OAUTH_SCOPES` - Scopes to request. Defaults to `openid email profile` 1. `OPENID_REDIRECT_URI` - The redirect URI configured in your OIDC application. This must be set to `/oauth/oidc/callback`. +#### Auth0 + +1. `AUTH0_AUDIENCE`: If the OIDC provider is Auth0, this optional value can be set to the specific Auth0 `audience` the token should be issued for; doing so will ensure the access token is a JWT. If not specified the default behavior will be the issuance of an opaque Auth0 access token. [More info here](https://support.auth0.com/center/s/article/opaque-versus-jwt-access-token) + :::warning **Common OIDC Mistakes:** From c1cf8284ebc30594a9e231578b3146f26ed64816 Mon Sep 17 00:00:00 2001 From: bitsofinfo Date: Thu, 4 Dec 2025 16:20:00 -0700 Subject: [PATCH 03/12] feat: OAUTH_AUDIENCE config --- docs/features/auth/sso/index.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/features/auth/sso/index.mdx b/docs/features/auth/sso/index.mdx index 6965d8d04..0e7d9f748 100644 --- a/docs/features/auth/sso/index.mdx +++ b/docs/features/auth/sso/index.mdx @@ -120,10 +120,7 @@ The following environment variables are used: 1. `OAUTH_PROVIDER_NAME` - Name of the provider to show on the UI, defaults to SSO 1. `OAUTH_SCOPES` - Scopes to request. Defaults to `openid email profile` 1. `OPENID_REDIRECT_URI` - The redirect URI configured in your OIDC application. This must be set to `/oauth/oidc/callback`. - -#### Auth0 - -1. `AUTH0_AUDIENCE`: If the OIDC provider is Auth0, this optional value can be set to the specific Auth0 `audience` the token should be issued for; doing so will ensure the access token is a JWT. If not specified the default behavior will be the issuance of an opaque Auth0 access token. [More info here](https://support.auth0.com/center/s/article/opaque-versus-jwt-access-token) +1. `OAUTH_AUDIENCE` - Optional `audience` value that will be passed to the oauth provider's authorization endpoint as an additional query parameter. :::warning From c6c50c497543833e5acaff21f5483436c2a9f697 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:27:15 +0100 Subject: [PATCH 04/12] Enhance env-configuration documentation for Redis Added documentation for Redis socket connection timeout and websocket Redis options. --- docs/getting-started/env-configuration.mdx | 43 ++++++++++++++++++++-- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5dec0df04..36788088e 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5118,6 +5118,35 @@ This option has no effect if `REDIS_SENTINEL_HOSTS` is defined. - Default: `open-webui` - Description: Customizes the Redis key prefix used for storing configuration values. This allows multiple Open WebUI instances to share the same Redis instance without key conflicts. When operating in Redis cluster mode, the prefix is formatted as `{prefix}:` (e.g., `{open-webui}:config:*`) to enable multi-key operations on configuration keys within the same hash slot. +#### `REDIS_SOCKET_CONNECT_TIMEOUT` + +- Type: `float` (seconds) or empty string for None +- Default: None (no timeout, uses redis-py library default) +- Description: Sets the socket connection timeout in seconds for Redis and Sentinel connections. This timeout applies to the initial TCP connection establishment. When set, it prevents indefinite blocking when attempting to connect to unreachable Redis nodes. + +:::danger + +**Critical for Redis Sentinel Deployments** + +Without a socket connection timeout, Redis Sentinel failover can cause the application to hang indefinitely when a master node goes offline. The application may become completely unresponsive and even fail to restart. + +For Sentinel deployments, it is **strongly recommended** to set this value (e.g., `REDIS_SOCKET_CONNECT_TIMEOUT=5`). + +::: + +:::warning + +**Interaction with WEBSOCKET_REDIS_OPTIONS** + +If you explicitly set `WEBSOCKET_REDIS_OPTIONS`, this variable will **not** apply to the AsyncRedisManager used for websocket communication. In that case, you must include `socket_connect_timeout` directly within `WEBSOCKET_REDIS_OPTIONS`: +```bash +WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}' +``` + +If `WEBSOCKET_REDIS_OPTIONS` is not set, `REDIS_SOCKET_CONNECT_TIMEOUT` will be applied to websocket connections automatically. + +::: + #### `ENABLE_WEBSOCKET_SUPPORT` - Type: `bool` @@ -5201,16 +5230,24 @@ This option has no effect if `WEBSOCKET_SENTINEL_HOSTS` is defined. #### `WEBSOCKET_REDIS_OPTIONS` - Type: `str` -- Default: `{}` -- Description: A string representation of a dictionary containing additional Redis connection options for the websocket Redis client. This allows you to specify advanced connection parameters such as SSL settings, timeouts, or other Redis client configurations that are not covered by the standard `WEBSOCKET_REDIS_URL`. The string should be formatted as a valid Python dictionary. For example: `{"retry_on_timeout": true, "socket_connect_timeout": 5, "socket_timeout": 5, "max_connections": 8}`. All JSON encodable options listed [here] (https://redis.readthedocs.io/en/stable/connections.html) can be used. +- Default: `{}` (empty, which allows `REDIS_SOCKET_CONNECT_TIMEOUT` to apply if set) +- Description: A string representation of a dictionary containing additional Redis connection options for the websocket Redis client (AsyncRedisManager). This allows you to specify advanced connection parameters such as SSL settings, timeouts, or other Redis client configurations that are not covered by the standard `WEBSOCKET_REDIS_URL`. The string should be formatted as valid JSON. For example: `{"retry_on_timeout": true, "socket_connect_timeout": 5, "socket_timeout": 5, "max_connections": 8}`. All JSON encodable options listed [here](https://redis.readthedocs.io/en/stable/connections.html) can be used. :::warning -**AWS SSM and Docker compose cannot ingest raw JSON, as such you need top escape any double quotes like the following:** +**AWS SSM and Docker compose cannot ingest raw JSON, as such you need to escape any double quotes like the following:** `{\"retry_on_timeout\": true, \"socket_connect_timeout\": 5, \"socket_timeout\": 5, \"max_connections\": 8}` ::: +:::info + +**Precedence with REDIS_SOCKET_CONNECT_TIMEOUT** + +When this variable is left empty (default), `REDIS_SOCKET_CONNECT_TIMEOUT` is automatically applied to websocket connections if set. However, if you explicitly set `WEBSOCKET_REDIS_OPTIONS` to any value, `REDIS_SOCKET_CONNECT_TIMEOUT` will **not** be injected—you must include `socket_connect_timeout` manually within this JSON if needed. + +::: + #### `WEBSOCKET_SERVER_LOGGING` - Type: `bool` From d14549c62e230a614c4f310d365d9bd7f4907b07 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:28:03 +0100 Subject: [PATCH 05/12] Update redis.md --- docs/tutorials/integrations/redis.md | 38 +++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/integrations/redis.md b/docs/tutorials/integrations/redis.md index 60bc7fef6..2e48e1daa 100644 --- a/docs/tutorials/integrations/redis.md +++ b/docs/tutorials/integrations/redis.md @@ -183,10 +183,41 @@ REDIS_KEY_PREFIX="open-webui" The `REDIS_KEY_PREFIX` allows multiple Open WebUI instances to share the same Redis instance without key conflicts. In Redis cluster mode, the prefix is formatted as `{prefix}:` (e.g., `{open-webui}:config:*`) to enable multi-key operations on configuration keys within the same hash slot. +### Sentinel Failover Configuration + +:::danger Critical: Socket Timeout for Sentinel Deployments + +Redis Sentinel setups require explicit socket connection timeout configuration to ensure proper failover behavior. Without a timeout, the application can hang indefinitely when a Redis master node goes offline—potentially preventing even application restarts. + +**Symptoms of missing timeout configuration:** +- Application becomes completely unresponsive during failover +- Application hangs on startup if the first Sentinel host is unreachable +- Recovery takes minutes instead of seconds after master failover + +**Required configuration:** +```bash +REDIS_SOCKET_CONNECT_TIMEOUT=5 +``` + +This sets a 5-second timeout for socket connection attempts to Redis/Sentinel nodes, allowing the application to fail over gracefully. + +::: + +:::warning + +**If using WEBSOCKET_REDIS_OPTIONS** + +When you explicitly set `WEBSOCKET_REDIS_OPTIONS`, `REDIS_SOCKET_CONNECT_TIMEOUT` does not automatically apply to websocket connections. You must include the timeout in both places: +```bash +REDIS_SOCKET_CONNECT_TIMEOUT=5 +WEBSOCKET_REDIS_OPTIONS='{"socket_connect_timeout": 5}' +``` + +::: + ### Complete Example Configuration Here's a complete example showing all Redis-related environment variables: - ```bash # Required for multi-worker/multi-instance deployments REDIS_URL="redis://redis-valkey:6379/0" @@ -196,10 +227,15 @@ ENABLE_WEBSOCKET_SUPPORT="true" WEBSOCKET_MANAGER="redis" WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1" +# Recommended for Sentinel deployments (prevents failover hangs) +REDIS_SOCKET_CONNECT_TIMEOUT=5 + # Optional REDIS_KEY_PREFIX="open-webui" ``` +For Redis Sentinel deployments specifically, ensure `REDIS_SOCKET_CONNECT_TIMEOUT` is set to prevent application hangs during master failover. + ### Docker Run Example When running Open WebUI using Docker, connect it to the same Docker network and include all necessary Redis variables: From fff5d6f45b8765497e0c4cc9706c364328378486 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:43:22 +0100 Subject: [PATCH 06/12] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 29 +++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 36788088e..17587ca58 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -12,7 +12,7 @@ As new variables are introduced, this page will be updated to reflect the growin :::info -This page is up-to-date with Open WebUI release version [v0.6.41](https://github.com/open-webui/open-webui/releases/tag/v0.6.41), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. +This page is up-to-date with Open WebUI release version [v0.6.42](https://github.com/open-webui/open-webui/releases/tag/v0.6.42), but is still a work in progress to later include more accurate descriptions, listing out options available for environment variables, defaults, and improving descriptions. ::: @@ -3197,6 +3197,21 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for: - Description: Specifies the timeout for Playwright requests. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `WEB_LOADER_TIMEOUT` + +- Type: `float` +- Default: Empty string (' '), since `None` is set as default. +- Description: Specifies the request timeout in seconds for the SafeWebBaseLoader when scraping web pages. Without this setting, web scraping operations can hang indefinitely on slow or unresponsive pages. Recommended values are 10–30 seconds depending on your network conditions. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::warning + +This **timeout only applies when `WEB_LOADER_ENGINE` is set to `safe_web`** (the default). It has no effect on Playwright or Firecrawl loader engines, which have their own timeout configurations (`PLAYWRIGHT_TIMEOUT` and Firecrawl's internal settings respectively). + +::: + +### YouTube Loader + ### YouTube Loader #### `YOUTUBE_LOADER_PROXY_URL` @@ -4274,6 +4289,18 @@ If `OAUTH_PICTURE_CLAIM` is set to `''` (empty string), then the OAuth picture c - Description: Specifies the allowed domains for OAuth authentication. (e.g., "example1.com,example2.com"). - Persistence: This environment variable is a `PersistentConfig` variable. +#### `OAUTH_AUDIENCE` + +- Type: `str` +- Default: Empty string (' ') +- Description: Specifies an audience parameter passed to the OAuth provider's authorization endpoint during login. Some providers (such as Auth0 and Ory) use this value to determine the type of access token returned—without it, providers typically return an opaque token, while with it, they return a JWT that can be decoded and validated. This parameter is not part of the official OAuth/OIDC spec for authorization endpoints but is widely supported by some providers. + +:::info + +This is useful when you need a JWT access token for downstream validation or when your OAuth provider requires an audience hint for proper token generation. For Auth0, this is typically your API identifier (e.g., `https://your-api.auth0.com/api/v2/`). For Ory, specify the resource server you want to access. + +::: + ## LDAP #### `ENABLE_LDAP` From 5e635a4fb7a4c0ef43f4d16ae8f628aca8d0c33b Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sun, 14 Dec 2025 18:45:40 +0100 Subject: [PATCH 07/12] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 9daa8e2c8..36fa2e4b6 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2889,6 +2889,13 @@ This environment variable was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". the search query. Example: `http://searxng.local/search?q=` - Persistence: This environment variable is a `PersistentConfig` variable. +#### `SEARXNG_LANGUAGE` + +- Type: `str` +- Default: `all` +- Description: This variable is used in the request to searxng as the "search language" (arguement "language"). +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `GOOGLE_PSE_API_KEY` - Type: `str` From 4142ff92fa683ec4edc9a63460e2fb4a0e6e8005 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Tue, 16 Dec 2025 11:25:30 +0100 Subject: [PATCH 08/12] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 36fa2e4b6..5fc17133b 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5210,8 +5210,8 @@ When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker c #### `WEBSOCKET_MANAGER` - Type: `str` -- Default: `redis` -- Description: Specifies the websocket manager to use (in this case, Redis). +- Default: `"" (empty string)` +- Description: Specifies the websocket manager to use. Allowed values include: `redis` :::warning From b1b0cf322dd1c69b610b3240fc404dbf599f65d3 Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:08:50 +0100 Subject: [PATCH 09/12] Add image tags information for production env in doc --- docs/getting-started/updating.mdx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index bab079753..7c7be78be 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -57,6 +57,33 @@ Status: Downloaded newer image for ghcr.io/open-webui/open-webui:main Your chat histories, settings, and uploaded files are stored in a Docker volume named `open-webui`. Pulling a new image does **not** affect this data. The volume persists independently of the container. ::: +### (Optional) Using image tags in production + +Open WebUI provides multiple Docker image tags depending on how you want to manage updates. + +If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup. + +Examples (latest version tags): +``` +ghcr.io/open-webui/open-webui:main +ghcr.io/open-webui/open-webui:cuda +ghcr.io/open-webui/open-webui:ollama +``` + +For `production environments` where stability and reproducibility are important, it is recommended to pin a specific release version instead of using these floating tags. + +Versioned images follow this format: +``` +ghcr.io/open-webui/open-webui:- +``` + +Examples (pinned versions — replace with the release version you want to use): +``` +ghcr.io/open-webui/open-webui:v0.6.41 +ghcr.io/open-webui/open-webui:v0.6.41-cuda +ghcr.io/open-webui/open-webui:v0.6.41-ollama +``` + ### Step 3: Start Container with Updated Image Recreate the container using the new image while mounting your existing data volume. From f34a32bc15b41756eeb1c0d71ecee85bc159ce7d Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:10:01 +0100 Subject: [PATCH 10/12] Remove useless line --- docs/getting-started/updating.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 7c7be78be..422f25337 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -60,7 +60,6 @@ Your chat histories, settings, and uploaded files are stored in a Docker volume ### (Optional) Using image tags in production Open WebUI provides multiple Docker image tags depending on how you want to manage updates. - If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup. Examples (latest version tags): From 39834100fb3465d0f87e461751598bcdbf0b9d4c Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:14:12 +0100 Subject: [PATCH 11/12] Mention pulling a specific Open WebUI version --- .../quick-start/tab-docker/ManualDocker.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index 9ceacfe8f..167a69973 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -18,6 +18,14 @@ For environments with limited storage or bandwidth, Open WebUI offers slim image docker pull ghcr.io/open-webui/open-webui:main-slim ``` +### Specific release version + +You can also pull a specific Open WebUI release version directly by using a versioned image tag. This is recommended for production environments to ensure stable and reproducible deployments. + +```bash +docker pull ghcr.io/open-webui/open-webui:v0.6.41 +``` + ## Step 2: Run the Container Run the container with default settings. This command includes a volume mapping to ensure persistent data storage. From 6cdbfdac3be548f34fc11ee36b3ec4f33e58da96 Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:20:28 +0100 Subject: [PATCH 12/12] Add image tags explication in homepage --- docs/intro.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/intro.mdx b/docs/intro.mdx index 72ce9a263..8b447c1e8 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -89,6 +89,22 @@ Both commands facilitate a built-in, hassle-free installation of both Open WebUI After installation, you can access Open WebUI at [http://localhost:3000](http://localhost:3000). Enjoy! 😄 +### Using image tags in production + +If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup, as shown in the examples above. +For `production environments` where stability and reproducibility are important, it is recommended to pin a specific release version instead of using these floating tags. Versioned images follow this format: + +``` +ghcr.io/open-webui/open-webui:- +``` + +Examples (pinned versions for illustration purposes only): +``` +ghcr.io/open-webui/open-webui:v0.6.41 +ghcr.io/open-webui/open-webui:v0.6.41-ollama +ghcr.io/open-webui/open-webui:v0.6.41-cuda +``` + ### Using the Dev Branch 🌙 :::warning