Merge pull request #872 from HennieLP/DocumentIntellIgenceModelConfiguration

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

docs/faq.mdx

@@ -7,25 +7,29 @@ import { TopBanners } from "@site/src/components/TopBanners";
 
 <TopBanners />
 
-### **Q: How do I customize the logo and branding?**
+### Q: How do I customize the logo and branding?
 
 **A:** You can customize the theme, logo, and branding with our **[Enterprise License](https://docs.openwebui.com/enterprise)**, which unlocks exclusive enterprise features.
 
 For more details on enterprise solutions and branding customizations, [click here](https://docs.openwebui.com/enterprise).
 
-### **Q: Why am I asked to sign up? Where are my data being sent to?**
+### Q: Is my data being sent anywhere?
+
+**A:** No, your data is never sent anywhere unless you explicitly choose to share it or you connect an external model provider. Everything inside Open WebUI runs and is stored locally on your machine or server, giving you full control over your data at all times. We encourage you not to simply take our word for it: our entire codebase is hosted publicly, so you can inspect exactly how everything works, and if you ever notice anything concerning, please report it to us on our repo immediately.
+
+### Q: Why am I asked to sign up? Where are my data being sent to?
 
 **A:** We require you to sign up to become the admin user for enhanced security. This ensures that if the Open WebUI is ever exposed to external access, your data remains secure. It's important to note that everything is kept local. We do not collect your data. When you sign up, all information stays within your server and never leaves your device. Your privacy and security are our top priorities, ensuring that your data remains under your control at all times.
 
-### **Q: Why can't my Docker container connect to services on the host using `localhost`?**
+### Q: Why can't my Docker container connect to services on the host using `localhost`?
 
 **A:** Inside a Docker container, `localhost` refers to the container itself, not the host machine. This distinction is crucial for networking. To establish a connection from your container to services running on the host, you should use the DNS name `host.docker.internal` instead of `localhost`. This DNS name is specially recognized by Docker to facilitate such connections, effectively treating the host as a reachable entity from within the container, thus bypassing the usual `localhost` scope limitation.
 
-### **Q: How do I make my host's services accessible to Docker containers?**
+### Q: How do I make my host's services accessible to Docker containers?
 
 **A:** To make services running on the host accessible to Docker containers, configure these services to listen on all network interfaces, using the IP address `0.0.0.0`, instead of `127.0.0.1` which is limited to `localhost` only. This configuration allows the services to accept connections from any IP address, including Docker containers. It's important to be aware of the security implications of this setup, especially when operating in environments with potential external access. Implementing appropriate security measures, such as firewalls and authentication, can help mitigate risks.
 
-### **Q: Why isn't my Open WebUI updating? I've re-pulled/restarted the container, and nothing changed.**
+### Q: Why isn't my Open WebUI updating? I've re-pulled/restarted the container, and nothing changed.
 
 **A:** Updating Open WebUI requires more than just pulling the new Docker image. Here’s why your updates might not be showing and how to ensure they do:
 
@@ -35,7 +39,7 @@ For more details on enterprise solutions and branding customizations, [click her
 
 This process updates the app while keeping your data safe.
 
-### **Q: Wait, why would I delete my container? Won't I lose my data?**
+### Q: Wait, why would I delete my container? Won't I lose my data?
 
 **A:** It's a common concern, but deleting a container doesn't mean you'll lose your data, provided you're using Docker volumes correctly. Here’s why:
 
@@ -44,7 +48,7 @@ This process updates the app while keeping your data safe.
 
 By following the correct update steps—pulling the new image, removing the old container without deleting the volume, and creating a new container with the updated image and the existing volume—your application code is updated while your data remains unchanged and safe.
 
-### **Q: Should I use the distro-packaged Docker or the official Docker package?**
+### Q: Should I use the distro-packaged Docker or the official Docker package?
 
 **A:** We recommend using the official Docker package over distro-packaged versions for running Open WebUI. The official Docker package is frequently updated with the latest features, bug fixes, and security patches, ensuring optimal performance and security. Additionally, it supports important functionalities like `host.docker.internal`, which may not be available in distro-packaged versions. This feature is essential for proper network configurations and connectivity within Docker containers.
 
@@ -52,35 +56,35 @@ By choosing the official Docker package, you benefit from consistent behavior ac
 
 Everything you need to run Open WebUI, including your data, remains within your control and your server environment, emphasizing our commitment to your privacy and security. For instructions on installing the official Docker package, please refer to the [Install Docker Engine](https://docs.docker.com/engine/install/) guide on Docker's official documentation site.
 
-### **Q: Is GPU support available in Docker?**
+### Q: Is GPU support available in Docker?
 
 **A:** GPU support in Docker is available but varies depending on the platform. Officially, GPU support is provided in Docker for Windows and Docker Engine on Linux. Other platforms, such as Docker Desktop for Linux and MacOS, do not currently offer GPU support. This limitation is important to consider for applications requiring GPU acceleration. For the best experience and to utilize GPU capabilities, we recommend using Docker on platforms that officially support GPU integration.
 
-### **Q: Why does Open WebUI emphasize the use of Docker?**
+### Q: Why does Open WebUI emphasize the use of Docker?
 
 **A:** The decision to use Docker stems from its ability to ensure consistency, isolate dependencies, and simplify deployment across different environments. Docker minimizes compatibility issues and streamlines the process of getting the WebUI up and running, regardless of the underlying system. It's a strategic choice by the project maintainers to harness these benefits, acknowledging that while Docker has a learning curve, the advantages for deployment and maintenance are significant. We understand Docker might not be everyone's preference; however, this approach is central to our project's design and operational efficiency. We view the project's commitment to Docker as a fundamental aspect and encourage those looking for different deployment methods to explore community-driven alternatives.
 
-### **Q: Why doesn't Speech-to-Text (STT) and Text-to-Speech (TTS) work in my deployment?**
+### Q: Why doesn't Speech-to-Text (STT) and Text-to-Speech (TTS) work in my deployment?
 
 **A:** The functionality of Speech-to-Text (STT) and Text-to-Speech (TTS) services in your deployment may require HTTPS to operate correctly. Modern browsers enforce security measures that restrict certain features, including STT and TTS, to only work under secure HTTPS connections. If your deployment is not configured to use HTTPS, these services might not function as expected. Ensuring your deployment is accessible over HTTPS can resolve these issues, enabling full functionality of STT/TTS features.
 
-### **Q: Why doesn't Open WebUI include built-in HTTPS support?**
+### Q: Why doesn't Open WebUI include built-in HTTPS support?
 
 **A:** While we understand the desire for an all-in-one solution that includes HTTPS support, we believe such an approach wouldn't adequately serve the diverse needs of our user base. Implementing HTTPS directly within the project could limit flexibility and may not align with the specific requirements or preferences of all users. To ensure that everyone can tailor their setup to their unique environment, we leave the implementation of HTTPS termination to the users for their production deployments. This decision allows for greater adaptability and customization. Though we don't offer official documentation on setting up HTTPS, community members may provide guidance upon request, sharing insights and suggestions based on their experiences.
 
-### **Q: I updated/restarted/installed some new software and now Open WebUI isn't working anymore!**
+### Q: I updated/restarted/installed some new software and now Open WebUI isn't working anymore!
 
 **A:** If your Open WebUI isn't launching post-update or installation of new software, it's likely related to a direct installation approach, especially if you didn't use a virtual environment for your backend dependencies. Direct installations can be sensitive to changes in the system's environment, such as updates or new installations that alter existing dependencies. To avoid conflicts and ensure stability, we recommend using a virtual environment for managing the `requirements.txt` dependencies of your backend. This isolates your Open WebUI dependencies from other system packages, minimizing the risk of such issues.
 
-### **Q: I updated/restarted and now my login isn't working anymore, I had to create a new account and all my chats are gone.**
+### Q: I updated/restarted and now my login isn't working anymore, I had to create a new account and all my chats are gone.
 
 **A:** This issue typically arises when a Docker container is created without mounting a volume for `/app/backend/data` or if the designated Open WebUI volume (usually named `open-webui` in our examples) was unintentionally deleted. Docker volumes are crucial for persisting your data across container lifecycles. If you find yourself needing to create a new account after a restart, it's likely you've initiated a new container without attaching the existing volume where your data resides. Ensure that your Docker run command includes a volume mount pointing to the correct data location to prevent data loss.
 
-### **Q: I tried to login and couldn't, made a new account and now I'm being told my account needs to be activated by an admin.**
+### Q: I tried to login and couldn't, made a new account and now I'm being told my account needs to be activated by an admin.
 
 **A:** This situation occurs when you forget the password for the initial admin account created during the first setup. The first account is automatically designated as the admin account. Creating a new account without access to the admin account will result in the need for admin activation. Avoiding the loss of the initial admin account credentials is crucial for seamless access and management of Open WebUI. See the [Resetting the Admin Password](troubleshooting/password-reset) guide for instructions on recovering the admin account.
 
-### **Q: Why can't Open WebUI start with an SSL error?**
+### Q: Why can't Open WebUI start with an SSL error?
 
 **A:** The SSL error you're encountering when starting Open WebUI is likely due to the absence of SSL certificates or incorrect configuration of [huggingface.co](https://huggingface.co/). To resolve this issue, you could set up a mirror for HuggingFace, such as [hf-mirror.com](https://hf-mirror.com/), and specify it as the endpoint when starting the Docker container. Use the `-e HF_ENDPOINT=https://hf-mirror.com/` parameter to define the HuggingFace mirror address in the Docker run command. For example, you can modify the Docker run command as follows:
 
@@ -88,7 +92,7 @@ Everything you need to run Open WebUI, including your data, remains within your
 docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main
 ```
 
-### **Q: RAG with Open WebUI is very bad or not working at all. Why?**
+### Q: RAG with Open WebUI is very bad or not working at all. Why?
 
 **A:** If you're using **Ollama**, be aware that Ollama sets the context length to **2048 tokens by default**. This means that none of the retrieved data might be used because it doesn't fit within the available context window.
 
@@ -96,40 +100,23 @@ To improve the performance of Retrieval-Augmented Generation (**RAG**) with Open
 
 To do this, configure your **Ollama model params** to allow a larger context window. You can check and modify this setting in your chat directly or from model editor page to enhance the RAG experience significantly.
 
-### **Q: Is MCP (Model Context Protocol) supported in Open WebUI?**
+### Q: Is MCP (Model Context Protocol) supported in Open WebUI?
 
-**A:** [Yes, Open WebUI officially supports MCP Tool Servers—but exclusively through an **OpenAPI-compliant proxy**](/features/plugin/tools/openapi-servers/mcp) ([openapi-servers](https://github.com/open-webui/openapi-servers)) for optimal compatibility, security, and maintainability.
+**A:** Yes, Open WebUI now includes **native support for MCP Streamable HTTP**, enabling direct, first-class integration with MCP tools that communicate over the standard HTTP transport. For any **other MCP transports or non-HTTP implementations**, you should use our official proxy adapter, **MCPO**, available at 👉 [https://github.com/open-webui/mcpo](https://github.com/open-webui/mcpo). MCPO provides a unified OpenAPI-compatible layer that bridges alternative MCP transports into Open WebUI safely and consistently. This architecture ensures maximum compatibility, strict security boundaries, and predictable tool behavior across different environments while keeping Open WebUI backend-agnostic and maintainable.
 
-To bridge MCP (and other backend protocols), we provide a purpose-built proxy implementation available at: 👉 [https://github.com/open-webui/mcpo](https://github.com/open-webui/mcpo)
+### Q: Why is the frontend integrated into the same Docker image? Isn't this unscalable or problematic?
-
-This design choice is motivated by several core principles:
-
-- 📘 Standards-First: OpenAPI is the de facto standard for RESTful service definitions and contract-driven service interoperability. By aligning integrations through OpenAPI, we enable reproducible, schema-driven behavior across upgrades and deployments.
-- 🔒 Security Model Isolation: Integrating MCP through a proxy allows us to sandbox and isolate backend protocol behavior, reducing attack surface and enabling boundary-level auditing, authentication, and observability.
-- ⚙️ Protocol Abstraction: Supporting heterogeneous backends (e.g., MCP) through a unified OpenAPI schema enables Open WebUI to remain backend-agnostic while maintaining predictable runtime behavior.
-- ⛓️ Decoupled Deployment Topology: The proxy-based architecture allows tool servers (like MCP) to evolve independently from frontend presentation, facilitating highly modular production environments or distributed workloads.
-
-In summary: MCP is supported — as long as the MCP Tool Server is fronted by an OpenAPI-compatible proxy. This architectural decision is deliberate and ensures that Open WebUI remains scalable, secure, and maintainable.
-
-### **Q: How often is Open WebUI updated?** (Release Schedule)
-
-**A:** We aim to ship **major releases weekly**, with **bug fixes and minor updates delivered as needed**. However, this is not a rigid schedule—some weeks may see multiple releases, while others might have none at all.
-
-To stay informed, you can follow release notes and announcements on our [GitHub Releases page](https://github.com/open-webui/open-webui/releases).
-
-### **Q: Why is the frontend integrated into the same Docker image? Isn't this unscalable or problematic?**
 
 The assumption that bundling the frontend with the backend is unscalable comes from a misunderstanding of how modern Single-Page Applications work. Open WebUI’s frontend is a static SPA, meaning it consists only of HTML, CSS, and JavaScript files with no runtime coupling to the backend. Because these files are static, lightweight, and require no separate server, including them in the same image has no impact on scalability. This approach simplifies deployment, ensures every replica serves the exact same assets, and eliminates unnecessary moving parts. If you prefer, you can still host the SPA on any CDN or static hosting service and point it to a remote backend, but packaging both together is the standard and most practical method for containerized SPAs.
 
-### **Q: Is Open WebUI scalable for large organizations or enterprise deployments?**
+### Q: Is Open WebUI scalable for large organizations or enterprise deployments?
 
-**A:** Yes—**Open WebUI is architected for massive scalability and production readiness.** It’s already trusted in deployments supporting extremely high user counts—**think tens or even hundreds of thousands of seats**—used by universities, multinational enterprises, and major organizations worldwide.
+**A:** Yes, **Open WebUI is architected for massive scalability and production readiness.** It’s already trusted in deployments supporting extremely high user counts—**think tens or even hundreds of thousands of seats**—used by universities, multinational enterprises, and major organizations worldwide.
 
 Open WebUI’s stateless, container-first architecture means you’re never bottlenecked by a single server. Through horizontal scaling, flexible storage backends, externalized authentication and database support, and full container orchestration compatibility (for example, Kubernetes or Docker Swarm), you can build robust, high-availability clusters to meet even the most demanding enterprise requirements.
 
 With the right infrastructure configuration, Open WebUI will effortlessly scale from pilot projects to mission-critical worldwide rollouts.
 
-### **Q: How can I deploy Open WebUI in a highly available, large-scale production environment?**
+### Q: How can I deploy Open WebUI in a highly available, large-scale production environment?
 
 **A:** For organizations with demanding uptime and scale requirements, Open WebUI is designed to plug into modern production environments:
 
@@ -145,6 +132,21 @@ If you’re planning a high-availability, enterprise-grade deployment, we recomm
 
 Open WebUI is designed from day one to not just handle, but thrive at scale—serving large organizations, universities, and enterprises worldwide.
 
-### **Need Further Assistance?**
+### Q: How often is Open WebUI updated? (Release Schedule)
+
+**A:** We aim to ship **major releases weekly**, with **bug fixes and minor updates delivered as needed**. However, this is not a rigid schedule—some weeks may see multiple releases, while others might have none at all.
+
+To stay informed, you can follow release notes and announcements on our [GitHub Releases page](https://github.com/open-webui/open-webui/releases).
+
+### Q: Where do I report non-compliant Open WebUI deployments that violate the license?
+
+If you encounter an Open WebUI deployment that appears to violate the Open WebUI license—such as removed branding where it is not permitted, misleading white-labeling, commercial misuse, or any form of unauthorized redistribution—you can confidentially report it to our compliance team.
+
+📩 **Email:** **[reports@openwebui.com](mailto:reports@openwebui.com)**
+Please include any relevant details (screenshots, URLs, description of usage, etc.) so we can investigate appropriately.
+
+We review every report in good faith and handle all submissions discreetly. Protecting the health, clarity, and integrity of the Open WebUI ecosystem helps us keep the project sustainable, fair, and openly accessible for everyone.
+
+### Need Further Assistance?
 
 If you have any further questions or concerns, please reach out to our [GitHub Issues page](https://github.com/open-webui/open-webui/issues) or our [Discord channel](https://discord.gg/5rJgQTnV4s) for more help and information.

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/features/image-generation-and-editing/comfyui.md

@@ -104,7 +104,6 @@ Open WebUI also supports image editing through ComfyUI, allowing you to modify e
 
 ![Screenshot of an image being edited in the chat using ComfyUI.](/images/image-generation-and-editing/comfyui-edit-image-in-chat.png)
 
-
 ### Deeper Dive: Mapping ComfyUI Nodes to Open WebUI
 
 Understanding the node ID mapping is often the biggest hurdle in integrating ComfyUI with an external service like Open WebUI. Integrating ComfyUI via API requires mapping Open WebUI's generic controls (e.g., "Model," "Width," "Prompt") to specific node inputs within your static ComfyUI workflow JSON.
@@ -278,7 +277,7 @@ This section provides a supplementary guide on setting up the FLUX.1 models for
 
 ## Configuring with SwarmUI
 
-SwarmUI utilizes ComfyUI as its backend. In order to get Open WebUI to work with SwarmUI you will have to append `ComfyBackendDirect` to the `ComfyUI Base URL`. Additionally, you will want to setup SwarmUI with LAN access. After aforementioned adjustments, setting up SwarmUI to work with Open WebUI will be the same as the steps for [ComfyUI Image Generation](#comfyui-image-generation) outlined above.
+SwarmUI utilizes ComfyUI as its backend. In order to get Open WebUI to work with SwarmUI you will have to append `ComfyBackendDirect` to the `ComfyUI Base URL`. Additionally, you will want to setup SwarmUI with LAN access. After aforementioned adjustments, setting up SwarmUI to work with Open WebUI will be the same as the steps for ComfyUI image generation outlined above.
 ![Install SwarmUI with LAN Access](https://github.com/user-attachments/assets/a6567e13-1ced-4743-8d8e-be526207f9f6)
 
 ### SwarmUI API URL

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.
 
 :::
 
@@ -299,7 +299,7 @@ This will run the Open WebUI on port `9999`. The `PORT` environment variable is
 
 - Type: `int`
 - Default: Empty string (' '), which disables the limit (equivalent to None)
-- Description: Sets the maximum buffer size in bytes for handling stream response chunks. When a single chunk exceeds this limit, the system returns an empty JSON object and skips subsequent oversized data until encountering normally-sized chunks. This prevents memory issues when dealing with extremely large responses from certain providers (e.g., models like gemini-2.5-flash-image or services returning extensive web search data exceeding). Set to an empty string or a negative value to disable chunk size limitations entirely.
+- Description: Sets the maximum buffer size in bytes for handling stream response chunks. When a single chunk exceeds this limit, the system returns an empty JSON object and skips subsequent oversized data until encountering normally-sized chunks. This prevents memory issues when dealing with extremely large responses from certain providers (e.g., models like gemini-2.5-flash-image or services returning extensive web search data exceeding). Set to an empty string or a negative value to disable chunk size limitations entirely. Recommended values are 16-20 MB (`16777216`) or larger depending on the image size of the image generation model (4K images may need even more).
 
 :::info
 
@@ -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/getting-started/updating.mdx

@@ -446,7 +446,7 @@ docker run --rm -v open-webui:/data alpine ls -lah /data
 1. Stop Open WebUI: `docker stop open-webui`
 2. Backup volume: `docker run --rm -v open-webui:/data -v $(pwd):/backup alpine tar czf /backup/openwebui-backup.tar.gz /data`
 3. Restore from backup if needed
-4. Check [Manual Migration Guide](./manual-database-migration) for database issues
+4. Check [Manual Migration Guide](../troubleshooting/manual-database-migration.md) for database issues
 
 ### Watchtower Updates Too Frequently
 
@@ -572,6 +572,6 @@ If the interface looks broken or old after updating:
 
 - [Open WebUI GitHub Releases](https://github.com/open-webui/open-webui/releases) - Version history and changelogs
 - [Environment Configuration Guide](https://docs.openwebui.com/getting-started/env-configuration) - All environment variables
-- [Manual Database Migration](troubleshooting/manual-database-migration.md) - Fix database issues after updates
+- [Manual Database Migration](../troubleshooting/manual-database-migration.md) - Fix database issues after updates
 - [Watchtower Documentation](https://watchtower.nickfedor.com/) - Advanced Watchtower configuration
 - [WUD Documentation](https://getwud.github.io/wud/) - What's Up Docker setup guide

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: