khanh.pndc/open-webui-docs
1
0
Fork 0
mirror of https://github.com/open-webui/docs.git synced 2025-12-12 07:29:49 +07:00
Code Issues Packages Projects Releases Wiki Activity

Update redis.md

Browse Source
This commit is contained in:
Classic298
2025-11-06 22:11:53 +01:00
committed by GitHub
parent ce5cc47370
commit 20364c627c
1 changed files with 264 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

283
docs/tutorials/integrations/redis.md
View File

@@ -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
**Important Note on Service Names**
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
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.
:::
### Multi-Worker Configuration
If you're running multiple Uvicorn workers on a single host, add this variable:
```bash
UVICORN_WORKERS="4" # Adjust based on your CPU cores
REDIS_URL="redis://redis-valkey:6379/0" # Required when UVICORN_WORKERS > 1
```
:::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
If you have properly set up Redis and configured Open WebUI, you should see the following log message when starting your Open WebUI instance:
`DEBUG:open_webui.socket.main:Using Redis to manage websockets.`
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:
```bash
docker exec -it redis-valkey redis-cli -p 6379 ping
```
This command should output `PONG` if the Redis instance is running correctly. If this command fails, you could try this command instead:
### 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.