diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 116b98bcfc..4c4c0c13d3 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1055,11 +1055,16 @@ directly. Ensure that no users are present in the database if you intend to turn - Docker Default: Randomly generated on first start - Description: Overrides the randomly generated string used for JSON Web Token. -:::info +:::warning -This variable is always needed when using OAUTH, especially in clustered environments, but even in single-process environments. +**Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS** -Otherwise, OAUTH issues may occur. +When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you **must** set this variable. Without it, the following issues will occur: + +- Session management will fail across workers +- Application state will be inconsistent between instances +- Websocket connections will not function properly in distributed setups +- Users may experience intermittent authentication failures ::: @@ -4305,18 +4310,33 @@ More information about this setting can be found [here](https://docs.sqlalchemy. ### Redis -#### `REDIS_URL` - - Type: `str` - Description: Specifies the URL of the Redis instance or cluster host for storing application state. - Examples: - `redis://localhost:6379/0` - `rediss://:password@localhost:6379/0` *(with password and TLS)* - - `rediss://redis-cluster.redis.svc.cluster.local:6379/0 ?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt &ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt` *(with mTLS)* + - `rediss://redis-cluster.redis.svc.cluster.local:6379/0?ssl_cert_reqs=required&ssl_certfile=/tls/redis/tls.crt&ssl_keyfile=/tls/redis/tls.key&ssl_ca_certs=/tls/redis/ca.crt` *(with mTLS)* + +:::warning + +**Required for Multi-Worker and Multi-Node Deployments** + +When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you **must** set the `REDIS_URL` value. Without it, the following issues will occur: + +- Session management will fail across workers +- Application state will be inconsistent between instances +- Websocket connections will not function properly in distributed setups +- Users may experience intermittent authentication failures + +Redis serves as the central state store that allows multiple Open WebUI instances to coordinate and share critical application data. + +::: :::info -When deploying Open WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the REDIS_URL value is set. Without it, session, persistency and consistency issues in the app state will occur as the workers would be unable to communicate. +**Single Instance Deployments** + +If you're running Open WebUI as a single instance with `UVICORN_WORKERS=1` (the default), Redis is **not required**. The application will function normally without it. ::: @@ -4355,9 +4375,16 @@ This option has no effect if `REDIS_SENTINEL_HOSTS` is defined. - Default: `True` - Description: Enables websocket support in Open WebUI. -:::info +:::warning + +**Required for Multi-Worker and Multi-Node Deployments** -When deploying Open WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the ENABLE_WEBSOCKET_SUPPORT value is set. Without it, websocket consistency and persistency issues will occur. +When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you **must** set this variable. Without it, the following issues will occur: + +- Session management will fail across workers +- Application state will be inconsistent between instances +- Websocket connections will not function properly in distributed setups +- Users may experience intermittent authentication failures ::: @@ -4367,9 +4394,16 @@ When deploying Open WebUI in a multi-node/worker cluster with a load balancer, y - Default: `redis` - Description: Specifies the websocket manager to use (in this case, Redis). -:::info +:::warning -When deploying Open WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the WEBSOCKET_MANAGER value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. +**Required for Multi-Worker and Multi-Node Deployments** + +When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you **must** set this variable. Without it, the following issues will occur: + +- Session management will fail across workers +- Application state will be inconsistent between instances +- Websocket connections will not function properly in distributed setups +- Users may experience intermittent authentication failures ::: @@ -4379,9 +4413,16 @@ When deploying Open WebUI in a multi-node/worker cluster with a load balancer, y - Default: `${REDIS_URL}` - Description: Specifies the URL of the Redis instance or cluster host for websocket communication. It is distinct from `REDIS_URL` and in practice, it is recommended to set both. -:::info +:::warning + +**Required for Multi-Worker and Multi-Node Deployments** + +When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker cluster with a load balancer (e.g. helm/kubectl/kubernetes/k8s, you **must** set this variable. Without it, the following issues will occur: -When deploying Open WebUI in a multi-node/worker cluster with a load balancer, you must ensure that the WEBSOCKET_REDIS_URL value is set and a key-value NoSQL database like Redis is used. Without it, websocket consistency and persistency issues will occur. +- Session management will fail across workers +- Application state will be inconsistent between instances +- Websocket connections will not function properly in distributed setups +- Users may experience intermittent authentication failures ::: @@ -4444,7 +4485,7 @@ For most deployments, the default browser cookie-based session management is suf When deploying in orchestrated environments like Kubernetes or using Helm charts, it's recommended to keep UVICORN_WORKERS set to 1. Container orchestration platforms already provide their own scaling mechanisms through pod replication, and using multiple workers inside containers can lead to resource allocation issues and complicate horizontal scaling strategies. -If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-instance setups are set accordingly. +If you use UVICORN_WORKERS, you also need to ensure that related environment variables for scalable multi-worker setups are set accordingly. ::: diff --git a/docs/tutorials/integrations/redis.md b/docs/tutorials/integrations/redis.md index 8f073a42b2..5e0a191de1 100644 --- a/docs/tutorials/integrations/redis.md +++ b/docs/tutorials/integrations/redis.md @@ -15,6 +15,45 @@ This tutorial is a community contribution and is not supported by the Open WebUI This documentation page outlines the steps required to integrate Redis with Open WebUI for websocket support. By following these steps, you will be able to enable websocket functionality in your Open WebUI instance, allowing for real-time communication and updates between clients and your application. +## When is Redis Required? + +Redis serves two distinct purposes in Open WebUI, and understanding when it's required is crucial for proper deployment: + +### Single Instance Deployments + +If you're running Open WebUI as a **single instance** with `UVICORN_WORKERS=1` (the default), Redis is **completely optional and not strictly needed**. The application will function normally without it for all operations. + +### Multi-Worker and Multi-Instance Deployments + +Redis becomes **mandatory** in the following scenarios: + +1. **Multiple Uvicorn Workers** (`UVICORN_WORKERS > 1`) + - Running multiple worker processes on a single host + - Requires Redis to share session state and application configuration between workers + +2. **Multi-Node Deployments** + - Kubernetes clusters with multiple pods + - Docker Swarm with multiple replicas + - Load-balanced setups with multiple Open WebUI instances + - Requires Redis to coordinate state across all instances + +3. **High Availability Setups** + - Any deployment pattern where multiple Open WebUI processes run simultaneously + - Requires Redis for session management, websocket coordination, and state synchronization + +:::warning + +**Critical Requirement** + +Without Redis in multi-worker or multi-instance scenarios, you will experience: +- Session management failures across workers +- Inconsistent application state between instances +- Non-functional websocket connections +- Intermittent authentication failures +- Loss of real-time chat updates + +::: + ### Prerequisites - A valid Open WebUI instance (running version 1.0 or higher) @@ -83,57 +122,263 @@ docker network create openwebui-network ## Configuring Open WebUI -To enable websocket support in Open WebUI, you will need to set the following environment variables for your Open WebUI instance: +To enable Redis support in Open WebUI, you need to configure different environment variables depending on your deployment type. +### Basic Configuration (All Deployments) + +For **all deployments** using Redis (single or multi-instance), set the following base environment variable: +```bash +REDIS_URL="redis://redis-valkey:6379/0" +``` + +This variable configures the primary Redis connection for application state management, session storage, and coordination between instances. + +### Websocket Configuration + +To enable websocket support specifically, add these additional environment variables: ```bash ENABLE_WEBSOCKET_SUPPORT="true" WEBSOCKET_MANAGER="redis" -WEBSOCKET_REDIS_URL="redis://redis:6379/1" +WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1" +``` + +:::info + +**Redis Database Numbers** + +Notice the different database numbers (`/0` vs `/1`) in the URLs: +- `REDIS_URL` uses database `0` for general application state +- `WEBSOCKET_REDIS_URL` uses database `1` for websocket-specific data + +This separation helps isolate different types of data. You can use the same database number for both if preferred, but using separate databases is recommended for better organization and potential performance optimization. + +::: + +### Optional Configuration +```bash REDIS_KEY_PREFIX="open-webui" ``` -These environment variables enable websocket support, specify Redis as the websocket manager, define the Redis URL, and set a custom Redis key prefix. 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. Make sure to replace the `WEBSOCKET_REDIS_URL` value with the actual IP address of your Redis instance. +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. -When running Open WebUI using Docker, you need to connect it to the same Docker network: +### 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" + +# Required for websocket support +ENABLE_WEBSOCKET_SUPPORT="true" +WEBSOCKET_MANAGER="redis" +WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1" + +# Optional +REDIS_KEY_PREFIX="open-webui" +``` + +### Docker Run Example + +When running Open WebUI using Docker, connect it to the same Docker network and include all necessary Redis variables: ```bash docker run -d \ --name open-webui \ --network openwebui-network \ -v open-webui:/app/backend/data \ + -p 3000:8080 \ + -e REDIS_URL="redis://redis-valkey:6379/0" \ -e ENABLE_WEBSOCKET_SUPPORT="true" \ -e WEBSOCKET_MANAGER="redis" \ - -e WEBSOCKET_REDIS_URL="redis://127.0.0.1:6379/1" \ + -e WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1" \ -e REDIS_KEY_PREFIX="open-webui" \ ghcr.io/open-webui/open-webui:main ``` -Replace `127.0.0.1` with the actual IP address of your Redis container in the Docker network. +:::warning -## Verification +**Important Note on Service Names** -If you have properly set up Redis and configured Open WebUI, you should see the following log message when starting your Open WebUI instance: +In the examples above, we use `redis://redis-valkey:6379` because: +- `redis-valkey` is the container name defined in the docker-compose.yml +- Docker's internal DNS resolves this name to the correct IP address within the network +- This is the recommended approach for Docker deployments -`DEBUG:open_webui.socket.main:Using Redis to manage websockets.` +Do **not** use `127.0.0.1` or `localhost` when connecting from one container to another - these refer to the container's own localhost, not the Redis container. -This confirms that Open WebUI is using Redis for websocket management. You can also use the `docker exec` command to verify that the Redis instance is running and accepting connections: +::: + +### Multi-Worker Configuration +If you're running multiple Uvicorn workers on a single host, add this variable: ```bash -docker exec -it redis-valkey redis-cli -p 6379 ping +UVICORN_WORKERS="4" # Adjust based on your CPU cores +REDIS_URL="redis://redis-valkey:6379/0" # Required when UVICORN_WORKERS > 1 ``` -This command should output `PONG` if the Redis instance is running correctly. If this command fails, you could try this command instead: +:::danger + +**Critical: Redis Required for UVICORN_WORKERS > 1** + +If you set `UVICORN_WORKERS` to any value greater than 1, you **must** configure `REDIS_URL`. Failing to do so will cause: +- Session state to be lost between requests +- Authentication to fail intermittently +- Application configuration to be inconsistent +- Websockets to malfunction + +::: + +## Verification + +### Verify Redis Connection +First, confirm that your Redis instance is running and accepting connections: ```bash docker exec -it redis-valkey valkey-cli -p 6379 ping ``` +This command should output `PONG` if the Redis instance is running correctly. + +### Verify Open WebUI Configuration + +After starting your Open WebUI instance with the proper Redis configuration, check the logs to confirm successful integration: + +#### Check for General Redis Connection + +Look for log messages indicating Redis is being used for application state: +```bash +docker logs open-webui 2>&1 | grep -i redis +``` + +#### Check for Websocket Redis Connection + +If you have enabled websocket support, you should see this specific log message: +``` +DEBUG:open_webui.socket.main:Using Redis to manage websockets. +``` + +To check this specifically: +```bash +docker logs open-webui 2>&1 | grep "Using Redis to manage websockets" +``` + +### Verify Redis Keys + +You can also verify that Open WebUI is actually writing data to Redis: +```bash +# List all Open WebUI keys +docker exec -it redis-valkey valkey-cli --scan --pattern "open-webui*" + +# Or with the default Redis CLI +docker exec -it redis-valkey redis-cli --scan --pattern "open-webui*" +``` + +If Redis is configured correctly, you should see keys with your configured prefix (e.g., `open-webui:session:*`, `open-webui:config:*`). + +### Test Multi-Worker Setup + +If you're running with `UVICORN_WORKERS > 1`, test that sessions persist across workers: + +1. Log in to Open WebUI +2. Refresh the page multiple times +3. You should remain logged in consistently + +If you're logged out randomly or see authentication errors, Redis is likely not configured correctly. + ## Troubleshooting -If you encounter issues with Redis or websocket support in Open WebUI, you can refer to the following resources for troubleshooting: +### Common Issues and Solutions + +#### Issue: "Connection to Redis failed" + +**Symptoms:** +- Error messages about Redis connection in logs +- Application fails to start or crashes +- Websockets don't work + +**Solutions:** +1. Verify Redis container is running: `docker ps | grep redis` +2. Check Redis is healthy: `docker exec -it redis-valkey valkey-cli ping` +3. Verify network connectivity: `docker network inspect openwebui-network` +4. Ensure the `REDIS_URL` uses the correct container name, not `127.0.0.1` or `localhost` +5. Check that both containers are on the same Docker network + +#### Issue: "Session lost after page refresh" (with UVICORN_WORKERS > 1) + +**Symptoms:** +- Users are logged out randomly +- Authentication works but doesn't persist +- Different behavior on each page refresh + +**Cause:** `REDIS_URL` is not configured when using multiple workers + +**Solution:** +Add the `REDIS_URL` environment variable: +```bash +REDIS_URL="redis://redis-valkey:6379/0" +``` + +#### Issue: "Websockets not working" + +**Symptoms:** +- Real-time chat updates don't appear +- Need to refresh page to see new messages +- Connection errors in browser console + +**Solutions:** +1. Verify all websocket environment variables are set: + - `ENABLE_WEBSOCKET_SUPPORT="true"` + - `WEBSOCKET_MANAGER="redis"` + - `WEBSOCKET_REDIS_URL="redis://redis-valkey:6379/1"` +2. Check logs for: `DEBUG:open_webui.socket.main:Using Redis to manage websockets.` +3. Verify Redis is accessible from Open WebUI container + +#### Issue: "Multiple Open WebUI instances interfering with each other" + +**Symptoms:** +- Configuration changes affect other instances +- Sessions conflict between deployments +- Unexpected behavior when running multiple Open WebUI installations + +**Solution:** +Use different `REDIS_KEY_PREFIX` values for each installation: +```bash +# Instance 1 +REDIS_KEY_PREFIX="openwebui-prod" + +# Instance 2 +REDIS_KEY_PREFIX="openwebui-dev" +``` + +#### Issue: "Redis memory usage growing continuously" + +**Symptoms:** +- Redis memory usage increases over time +- Container eventually runs out of memory + +**Solutions:** +1. Configure Redis maxmemory policy: +```yml + command: "valkey-server --save 30 1 --maxmemory 256mb --maxmemory-policy allkeys-lru" +``` +2. Monitor Redis memory: `docker exec -it redis-valkey valkey-cli info memory` +3. Clear old keys if needed: `docker exec -it redis-valkey valkey-cli FLUSHDB` + +### Additional Resources - [Redis Documentation](https://redis.io/docs) +- [Valkey Documentation](https://valkey.io/docs/) - [Docker Compose Documentation](https://docs.docker.com/compose/overview/) +- [Open WebUI Environment Variables](https://docs.openwebui.com/getting-started/env-configuration/) - [sysctl Documentation](https://man7.org/linux/man-pages/man8/sysctl.8.html) -By following these steps and troubleshooting tips, you should be able to set up Redis with Open WebUI for websocket support and enable real-time communication and updates between clients and your application. +### Getting Help + +If you continue to experience issues after following this guide: + +1. Check the [Open WebUI GitHub Issues](https://github.com/open-webui/open-webui/issues) +2. Review your complete configuration for typos +3. Verify all containers can communicate on the Docker network +4. Collect relevant logs from both Open WebUI and Redis containers +5. Join the [Open WebUI Discord](https://discord.gg/5rJgQTnV4s) for community support + +By following these steps and troubleshooting tips, you should be able to set up Redis with Open WebUI for both application state management and websocket support, enabling reliable multi-instance deployments and real-time communication between clients and your application.