Merge pull request #872 from HennieLP/DocumentIntellIgenceModelConfiguration

Added documentation for Redis socket connection timeout and websocket Redis options.

docs/features/auth/sso/index.mdx

@@ -120,6 +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 `<open-webui>/oauth/oidc/callback`.
+1. `OAUTH_AUDIENCE` - Optional `audience` value that will be passed to the oauth provider's authorization endpoint as an additional query parameter.
 
 :::warning
 

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.
 
 :::
 
@@ -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`
@@ -3197,6 +3204,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 +4296,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`
@@ -5118,6 +5152,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 +5264,24 @@ This option has no effect if `WEBSOCKET_SENTINEL_HOSTS` is defined.
 #### `WEBSOCKET_REDIS_OPTIONS`
 
 - Type: `str`
-- Default: `{}`
+- 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. 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.
+- 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`

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: