diff --git a/docs/features/interface/banners.md b/docs/features/interface/banners.md index 6f0bf152a1..2d23a19459 100644 --- a/docs/features/interface/banners.md +++ b/docs/features/interface/banners.md @@ -5,54 +5,73 @@ title: "🔰 Customizable Banners" ## Overview -Open WebUI provides a feature that allows administrators to create customizable banners with persistence in the `config.json` file. These banners can feature options for content, background color (info, warning, error, or success), and dismissibility. Banners are accessible only to logged-in users, ensuring the confidentiality of sensitive information. +Open WebUI allows administrators to display custom banners to logged-in users. This feature is useful for making announcements, displaying system-wide alerts, or sharing important information. Banners are persistent and can be configured to be dismissible by users. -## Configuring Banners through the Admin Panel +You can configure banners in two ways: through the Admin Panel for a user-friendly experience, or via environment variables for automated or GitOps-style deployments. -To configure banners through the admin panel, follow these steps: +## Configuring Banners -1. Log in to your Open WebUI instance as an administrator. -2. Navigate to the `Admin Panel` -> `Settings` -> `Interface`. -3. Locate the `Banners` option directly above the `Default Prompt Suggestions` option. -4. Click on the `+` icon to add a new banner. -5. Select the banner type and set the banner text as desired. -6. Choose whether the banner is dismissible or not. -7. Set the timestamp for the banner (optional). -8. Press `Save` at the bottom of the page to save the banner. +### Option 1: Using the Admin Panel -## Configuring Banners through Environment Variables +This is the most straightforward way to manage banners. -Alternatively, you can configure banners through environment variables. To do this, you will need to set the `WEBUI_BANNERS` environment variable with a list of dictionaries in the following format: +1. **Log in** to your Open WebUI instance as an administrator. +2. Navigate to the **Admin Panel** > **Settings** > **Interface**. +3. Locate the **"Banners"** section. +4. Click the **+** icon to add a new banner. -```json -[{"id": "string","type": "string [info, success, warning, error]","title": "string","content": "string","dismissible": False,"timestamp": 1000}] -``` +You can then configure the following options for each banner: + +- **Type:** The color and style of the banner. Choose from: + - `info` (Blue) + - `success` (Green) + - `warning` (Yellow) + - `error` (Red) +- **Title:** The main heading of the banner. +- **Content:** The main text or message of the banner. +- **Dismissible:** If toggled on, users can close the banner. Dismissed banners are stored in the user's browser, so they will not reappear for that user unless their browser cache is cleared. If toggled off, the banner will always be visible. + +5. Click **"Save"** at the bottom of the page to apply your changes. + +### Option 2: Using Environment Variables + +For automated deployments, you can configure banners using the `WEBUI_BANNERS` environment variable. The variable should be a JSON string representing a list of banner objects. -For more information on configuring environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration#webui_banners). +**Environment Variable:** -## Environment Variable Description +- `WEBUI_BANNERS` + - **Type:** `string` (containing a JSON list of objects) + - **Default:** `[]` + - **Description:** A list of banner objects to be displayed to users. + +**Example:** + +Here is an example of how to set the `WEBUI_BANNERS` variable in a `docker-compose.yml` file: + +```yaml +services: + open-webui: + image: ghcr.io/open-webui/open-webui:main + environment: + - 'WEBUI_BANNERS=[{"id":"update-2024-07-26","type":"info","title":"System Update","content":"A system update is scheduled for this Friday at 10 PM. Expect brief downtime.","dismissible":true},{"id":"policy-reminder","type":"warning","title":"Policy Reminder","content":"Please remember to adhere to the company-wide usage policy.","dismissible":false}]' +``` -- `WEBUI_BANNERS`: - - Type: list of dict - - Default: `[]` - - Description: List of banners to show to users. +## Banner Object Properties -## Banner Options +Each banner object in the JSON list has the following properties: -- `id`: Unique identifier for the banner. -- `type`: Background color of the banner (info, success, warning, error). -- `title`: Title of the banner. -- `content`: Content of the banner. -- `dismissible`: Whether the banner is dismissible or not. -- `timestamp`: Timestamp for the banner (optional). +- `id` (string, required): A unique identifier for the banner. This is used to track which banners a user has dismissed. +- `type` (string, required): The style of the banner. Must be one of `info`, `success`, `warning`, or `error`. +- `title` (string, required): The title text displayed on the banner. +- `content` (string, required): The main message of the banner. +- `dismissible` (boolean, required): Determines if the user can close the banner. `true` means it can be dismissed; `false` means it cannot. +- `timestamp` (integer, optional): **Note:** While this field is present in the configuration, it is not currently used by the frontend. The timestamp does not affect whether a banner is displayed or not. -## FAQ +## Troubleshooting -- Q: Can I configure banners through the admin panel? -A: Yes, you can configure banners through the admin panel by navigating to `Admin Panel` -> `Settings` -> `Interface` and clicking on the `+` icon to add a new banner. -- Q: Can I configure banners through environment variables? -A: Yes, you can configure banners through environment variables by setting the `WEBUI_BANNERS` environment variable with a list of dictionaries. -- Q: What is the format for the `WEBUI_BANNERS` environment variable? -A: The format for the `WEBUI_BANNERS` environment variable is a list of dictionaries with the following keys: `id`, `type`, `title`, `content`, `dismissible`, and `timestamp`. -- Q: Can I make banners dismissible? -A: Yes, you can make banners dismissible by setting the `dismissible` key to `True` in the banner configuration or by toggling dismissibility for a banner within the UI. +- **Banner Not Appearing:** + - Ensure the JSON format for the `WEBUI_BANNERS` environment variable is correct. It must be a valid JSON array of objects. + - Check the Open WebUI server logs for any errors related to parsing the `WEBUI_BANNERS` variable. +- **Banner Cannot Be Dismissed:** + - Verify that the `dismissible` property for the banner is set to `true` in your configuration. + - If a banner is not dismissible, it is by design and cannot be closed by the user. diff --git a/docs/features/interface/webhooks.md b/docs/features/interface/webhooks.md index e7ae8e841c..3546202c70 100644 --- a/docs/features/interface/webhooks.md +++ b/docs/features/interface/webhooks.md @@ -5,56 +5,101 @@ title: "🪝 Webhook Integrations" ## Overview -Open WebUI provides a webhook feature that allows you to receive notifications automatically whenever new users sign up to your instance. This is done by providing a webhook URL to Open WebUI, which will then send notifications to that URL when a new user account is created. +Open WebUI offers two distinct webhook integrations to help you stay informed about events happening within your instance. These webhooks allow you to receive automated notifications in external services like Discord, Slack, or any other application that supports incoming webhooks. -## Configuring Webhooks in Open WebUI +There are two types of webhooks available: -You will need to obtain a webhook URL from an external service that supports webhooks, such as a Discord channel or a Slack workspace. This URL will be used to receive notifications from Open WebUI. +1. **Admin Webhook:** A system-wide webhook that notifies administrators about new user sign-ups. +2. **User Webhook:** A personal webhook that notifies individual users when a response to their chat is ready, especially useful for long-running tasks. -To configure webhooks in Open WebUI, you have two options: +## 1. Admin Webhook: New User Notifications -### Option 1: Configure through the Admin Interface +This webhook is designed for administrators to monitor new user registration on the Open WebUI instance. -1. Log in to your Open WebUI instance as an administrator. -2. Navigate to the `Admin Panel`. -3. Click the `Settings` tab located at the top. -4. From there, navigate to the `General` sectionn of the setting in the admin panel. -5. Locate the `Webhook URL` field and enter the webhook URL. -6. Save the changes. +### Use Case -### Option 2: Configure through Environment Variables +- **User Registration Tracking:** Receive a real-time notification in a dedicated Slack or Discord channel whenever a new user creates an account. This helps you keep track of your user base and welcome new members. -Alternatively, you can configure the webhook URL by setting the `WEBHOOK_URL` environment variable. For more information on environment variables in Open WebUI, see [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration/#webhook_url). +### Configuration -### Step 3: Verify the Webhook +You can configure the admin webhook in two ways: -To verify that the webhook is working correctly, create a new user account in Open WebUI. If the webhook is configured correctly, you should receive a notification at the specified webhook URL. +#### Option 1: Through the Admin Panel -## Webhook Payload Format +1. Log in as an administrator. +2. Navigate to **Admin Panel > Settings > General**. +3. Locate the **"Webhook URL"** field. +4. Enter the webhook URL provided by your external service (e.g., Discord, Slack). +5. Click **"Save"**. -The webhook payload sent by Open WebUI is in plain text and contains a simple notification message about the new user account. The payload format is as follows: +#### Option 2: Through Environment Variables -```txt -New user signed up: +You can also set the webhook URL using the `WEBHOOK_URL` environment variable. For more details, refer to the [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration/#webhook_url) documentation. + +### Payload Format + +When a new user signs up, Open WebUI will send a `POST` request to the configured URL with a JSON payload containing the new user's details. + +**Payload Example:** + +```json +{ + "event": "new_user", + "user": { + "email": "tim@example.com", + "name": "Tim" + } +} ``` -For example, if a user named "Tim" signs up, the payload sent would be: +## 2. User Webhook: Chat Response Notifications + +This webhook allows individual users to receive a notification when a model has finished generating a response to their prompt. It's particularly useful for long-running tasks where you might navigate away from the Open WebUI tab. + +### Use Case + +- **Long-Running Task Alerts:** If you submit a complex prompt that takes several minutes to process, you can close the browser tab and still be notified the moment the response is ready. This allows you to work on other tasks without having to constantly check the Open WebUI interface. + +### How it Works -```txt -New user signed up: Tim +The notification is only sent if you are **not actively using the WebUI**. If you have the tab open and focused, the webhook will not be triggered, preventing unnecessary notifications. + +### Configuration + +1. Click on your profile picture in the bottom-left corner to open the settings menu. +2. Navigate to **Settings > Account**. +3. Locate the **"Notification Webhook"** field. +4. Enter your personal webhook URL. +5. Click **"Save"**. + +### Payload Format + +When a chat response is ready and you are inactive, Open WebUI will send a `POST` request to your webhook URL with a JSON payload containing details about the chat. + +**Payload Example:** + +```json +{ + "event": "chat_response", + "chat": { + "id": "abc-123-def-456", + "title": "My Awesome Conversation", + "last_message": "This is the prompt I submitted." + } +} ``` ## Troubleshooting -- Make sure the webhook URL is correct and properly formatted. -- Verify that the webhook service is enabled and configured correctly. -- Check the Open WebUI logs for any errors related to the webhook. -- Verify the connection hasn't been interrupted or blocked by a firewall or proxy. -- The webhook server could be temporarily unavailable or experiencing high latency. -- If provided through the webhook service, verify if the Webhook API key is invalid, expired, or revoked. +If you're not receiving webhook notifications, here are a few things to check: + +- **Verify the URL:** Ensure the webhook URL is correct and properly pasted into the settings field. +- **Service Configuration:** Double-check that the webhook is set up correctly in the external service (e.g., Discord, Slack). +- **Firewall/Proxy:** Make sure your network or firewall is not blocking outgoing requests from the Open WebUI server. +- **Open WebUI Logs:** Check the Open WebUI server logs for any error messages related to webhook failures. :::note -Note: The webhook feature in Open WebUI is still evolving, and we plan to add more features and event types in the future. +The webhook features in Open WebUI are continuously being improved. Stay tuned for more event types and customization options in future updates. ::: diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 9632ea07e7..bdcd9a0e41 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1187,6 +1187,13 @@ pip install open-webui[all] ::: +:::info + +Only PGVector and ChromaDB will be consistently maintained by the Open WebUI team. +The other vector stores are community-added vector databases. + +::: + ### ChromaDB #### `CHROMA_TENANT` @@ -1289,6 +1296,13 @@ pip install open-webui[all] ### Milvus +:::warning + +Milvus is not actively maintained by the Open WebUI team. It is an addition by the community and is maintained by the community. +If you want to use Milvus, be careful when upgrading Open WebUI (crate backups and snapshots for rollbacks) in case internal changes in Open WebUI lead to breakage. + +::: + #### `MILVUS_URI` - Type: `str` @@ -1425,9 +1439,7 @@ After successful migration (from milvus to multitenancy milvus), legacy collecti - Collection naming dependency: Multitenancy relies on Open WebUI's internal collection naming conventions (user-memory-, file-, web-search-, hash patterns). **If Open WebUI changes these conventions in future updates, multitenancy routing may break, causing data corruption or incorrect data retrieval across isolated resources.** - No automatic rollback: Disabling multitenancy after data is written will not restore access to the shared collections. Data would need manual extraction and re-import. -**For fresh installations:** -- Multitenancy is recommended and enabled by default (true) -- No migration concerns exist +For fresh installations, no migration concerns exist **For existing installations with valuable data:** - Do not migrate to multitenancy mode if you do not want to handle migration and risk data loss @@ -1445,6 +1457,17 @@ After successful migration (from milvus to multitenancy milvus), legacy collecti ::: +:::warning + +The mapping of multitenancy relies on current Open WebUI naming conventions for collection names. + +If Open WebUI changes how it generates collection names (e.g., "user-memory-" prefix, "file-" prefix, web search patterns, or hash formats), this mapping will break and route data to incorrect collections. +POTENTIALLY CAUSING HUGE DATA CORRUPTION, DATA CONSISTENCY ISSUES AND INCORRECT DATA MAPPING INSIDE THE DATABASE. + +If you use Multitenancy Mode, you should always check for any changes to the collection names and data mapping before upgrading, and upgrade carefully (snapshots and backups for rollbacks)! + +::: + #### `MILVUS_COLLECTION_PREFIX` - Type: `str` @@ -1522,6 +1545,13 @@ If set to `false`, open-webui will assume the postgreSQL database where embeddin ### Qdrant +:::warning + +Qdrant is not actively maintained by the Open WebUI team. It is an addition by the community and is maintained by the community. +If you want to use Qdrant, be careful when upgrading Open WebUI (crate backups and snapshots for rollbacks) in case internal changes in Open WebUI lead to breakage. + +::: + #### `QDRANT_API_KEY` - Type: `str` @@ -1594,6 +1624,17 @@ If you decide to use the multitenancy pattern as your default and you don't need ::: +:::warning + +The mapping of multitenancy relies on current Open WebUI naming conventions for collection names. + +If Open WebUI changes how it generates collection names (e.g., "user-memory-" prefix, "file-" prefix, web search patterns, or hash formats), this mapping will break and route data to incorrect collections. +POTENTIALLY CAUSING HUGE DATA CORRUPTION, DATA CONSISTENCY ISSUES AND INCORRECT DATA MAPPING INSIDE THE DATABASE. + +If you use Multitenancy Mode, you should always check for any changes to the collection names and data mapping before upgrading, and upgrade carefully (snapshots and backups for rollbacks)! + +::: + #### `QDRANT_COLLECTION_PREFIX` - Type: `str` diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index a5c262357b..4a6eb8f183 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -8,6 +8,7 @@ import TabItem from '@theme/TabItem'; import { TopBanners } from "@site/src/components/TopBanners"; import DockerCompose from './tab-docker/DockerCompose.md'; +import Extension from './tab-docker/DockerDesktopExtension.md'; import Podman from './tab-docker/Podman.md'; import PodmanKubePlay from './tab-docker/PodmanKubePlay.md'; import ManualDocker from './tab-docker/ManualDocker.md'; @@ -55,19 +56,25 @@ Choose your preferred installation method below: + +
+ +
+ +
- +
- +
diff --git a/docs/getting-started/quick-start/tab-docker/DockerDesktopExtension.md b/docs/getting-started/quick-start/tab-docker/DockerDesktopExtension.md new file mode 100644 index 0000000000..cefc78a146 --- /dev/null +++ b/docs/getting-started/quick-start/tab-docker/DockerDesktopExtension.md @@ -0,0 +1,6 @@ +# Docker Desktop Extension +Docker has released an Open WebUI Docker extension that uses Docker Model Runner for inference. You can read their getting started blog here: [Run Local AI with Open WebUI + Docker Model Runner](https://www.docker.com/blog/open-webui-docker-desktop-model-runner/) + +You can find troubleshooting steps for the extension in their Github repository: [Open WebUI Docker Extension - Troubleshooting](https://github.com/rw4lll/open-webui-docker-extension?tab=readme-ov-file#troubleshooting) + +While this is an amazing resource to try out Open WebUI with little friction, it is not an officially supported installation method - you may run into unexpected bugs or behaviors while using it. For example, you are not able to log in as different users in the extension since it is designed to be for a single local user. If you run into issues using the extension, please submit an issue on the extension's [Github repository](https://github.com/rw4lll/open-webui-docker-extension). diff --git a/docs/tutorials/integrations/redis.md b/docs/tutorials/integrations/redis.md index 5e0a191de1..6b7e153b3c 100644 --- a/docs/tutorials/integrations/redis.md +++ b/docs/tutorials/integrations/redis.md @@ -46,6 +46,7 @@ Redis becomes **mandatory** in the following scenarios: **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 @@ -127,6 +128,7 @@ To enable Redis support in Open WebUI, you need to configure different environme ### 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" ``` @@ -136,17 +138,36 @@ This variable configures the primary Redis connection for application state mana ### 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-valkey:6379/1" ``` +:::danger Critical: Configure CORS for WebSocket Connections + +A very common and difficult-to-debug issue with WebSocket connections is a misconfigured Cross-Origin Resource Sharing (CORS) policy. If your Open WebUI instance is accessed from a different domain or port than the backend (e.g., behind a reverse proxy), you **must** set the `CORS_ALLOW_ORIGIN` environment variable. This variable tells the server which origins are permitted to access its resources. + +Failure to configure this correctly will cause WebSocket connections to fail silently or with cryptic browser errors and forgetting to set this variable is a common cause of WebSocket connection issues. + +**Example:** +If you access your UI at `https://my-open-webui.com`, you must set: + +```bash +CORS_ALLOW_ORIGIN="https://my-open-webui.com" +``` + +You can also provide a semicolon-separated list of allowed domains. **Do not skip this step in a production or reverse-proxied setup.** + +::: + :::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 @@ -155,6 +176,7 @@ This separation helps isolate different types of data. You can use the same data ::: ### Optional Configuration + ```bash REDIS_KEY_PREFIX="open-webui" ``` @@ -164,6 +186,7 @@ The `REDIS_KEY_PREFIX` allows multiple Open WebUI instances to share the same Re ### 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" @@ -180,6 +203,7 @@ 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 \ @@ -199,6 +223,7 @@ docker run -d \ **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 @@ -210,6 +235,7 @@ Do **not** use `127.0.0.1` or `localhost` when connecting from one container to ### 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 @@ -220,6 +246,7 @@ REDIS_URL="redis://redis-valkey:6379/0" # Required when UVICORN_WORKERS > 1 **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 @@ -232,6 +259,7 @@ If you set `UVICORN_WORKERS` to any value greater than 1, you **must** configure ### 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 ``` @@ -245,6 +273,7 @@ After starting your Open WebUI instance with the proper Redis configuration, che #### 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 ``` @@ -252,11 +281,13 @@ 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" ``` @@ -264,6 +295,7 @@ 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*" @@ -291,11 +323,13 @@ If you're logged out randomly or see authentication errors, Redis is likely not #### 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` @@ -305,6 +339,7 @@ If you're logged out randomly or see authentication errors, Redis is likely not #### 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 @@ -313,6 +348,7 @@ If you're logged out randomly or see authentication errors, Redis is likely not **Solution:** Add the `REDIS_URL` environment variable: + ```bash REDIS_URL="redis://redis-valkey:6379/0" ``` @@ -320,11 +356,13 @@ 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"` @@ -335,12 +373,14 @@ REDIS_URL="redis://redis-valkey:6379/0" #### 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" @@ -352,14 +392,18 @@ 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` diff --git a/docs/tutorials/tab-nginx/NginxProxyManager.md b/docs/tutorials/tab-nginx/NginxProxyManager.md index 6e13052c2f..8f019c5574 100644 --- a/docs/tutorials/tab-nginx/NginxProxyManager.md +++ b/docs/tutorials/tab-nginx/NginxProxyManager.md @@ -71,6 +71,23 @@ docker-compose up -d - Set the scheme to HTTP (default), enable ``Websockets support`` and point to your Docker IP (if docker with open-webui is running on the same computer as NGINX manager, this will be the same IP as earlier (example: ``192.168.0.6``) - Select the SSL certificate generated earlier, force SSL, and enable HTTP/2. +:::danger Critical: Configure CORS for WebSocket Connections + +A very common and difficult-to-debug issue with WebSocket connections is a misconfigured Cross-Origin Resource Sharing (CORS) policy. When running Open WebUI behind a reverse proxy like Nginx Proxy Manager, you **must** set the `CORS_ALLOW_ORIGIN` environment variable in your Open WebUI configuration. + +Failure to do so will cause WebSocket connections to fail, even if you have enabled "Websockets support" in Nginx Proxy Manager. + +**Example:** +If you access your UI at `https://openwebui.hello.duckdns.org`, you must set: + +```bash +CORS_ALLOW_ORIGIN="https://openwebui.hello.duckdns.org" +``` + +You can also provide a semicolon-separated list of allowed domains. **Do not skip this step.** + +::: + 6. **Add your url to open-webui (otherwise getting HTTPS error):** - Go to your open-webui → Admin Panel → Settings → General diff --git a/docs/tutorials/web-search/exa.md b/docs/tutorials/web-search/exa.md index 76812f0e43..1ea44bb15b 100644 --- a/docs/tutorials/web-search/exa.md +++ b/docs/tutorials/web-search/exa.md @@ -1,6 +1,6 @@ --- sidebar_position: 4 -title: "Exa" +title: "Exa AI" --- :::warning @@ -8,3 +8,64 @@ title: "Exa" This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial. ::: + +# Exa AI Web Search Integration + +This guide provides instructions on how to integrate [Exa AI](https://exa.ai/), a modern AI-powered search engine, with Open WebUI for web search capabilities. + +## Overview + +Exa AI is a search engine designed for AI applications, providing a suite of tools through its API, including web search, website crawling, and deep research functionalities. By integrating Exa AI with Open WebUI, you can leverage its powerful search capabilities directly within your chat interface. + +## Pricing Model + +Exa AI operates on a credit-based, pay-as-you-go pricing model. It is not a permanently free service, but it offers a trial for new users to evaluate the API. + +- **Initial Free Credits:** New users receive an initial grant of $10 worth of credits to test the API. +- **Pay-as-you-go:** Once the initial credits are depleted, you must move to a paid plan to continue using the service. The free tier is intended for evaluation purposes only and does not include a fixed monthly allowance. + +For detailed and up-to-date pricing information, please visit the [Exa AI pricing page](https://exa.ai/pricing). + +## Configuration Steps + +### 1. Obtain an Exa AI API Key + +First, you need to sign up for an Exa AI account and get an API key. + +1. **Sign Up:** Go to the [Exa AI website](https://exa.ai/) and create a new account. +2. **Navigate to API Keys:** Once you have signed up and logged in, navigate to the **API Keys** page in your user dashboard. +3. **Copy Your API Key:** On the API Keys page, you will find your unique API key. Copy this key to your clipboard, as you will need it to configure Open WebUI. + +### 2. Configure Open WebUI + +Next, you need to configure the Exa AI integration in the Open WebUI admin settings. + +1. **Log in as an Administrator:** Access your Open WebUI instance and log in with an administrator account. +2. **Navigate to Web Search Settings:** Go to the **Admin Panel**, then click on **Settings** > **Web Search**. +3. **Select Exa as the Search Engine:** In the "Web Search Engine" dropdown menu, select **Exa**. +4. **Enter Your API Key:** In the **Exa API Key** input field that appears, paste the API key you copied from the Exa AI dashboard. +5. **Save Changes:** Scroll down and click the **Save** button to apply the changes. + +### 3. (Optional) Environment Variable Configuration + +Alternatively, you can configure the Exa AI integration using an environment variable. This is particularly useful for Docker-based deployments. + +Set the following environment variable for your Open WebUI instance: + +- `EXA_API_KEY`: Your Exa AI API key. + +When this environment variable is set, the "Exa API Key" field in the admin settings will be automatically populated. + +**Example Docker `run` command:** + +```bash +docker run -d \\ + -p 3000:8080 \\ + -e EXA_API_KEY="your-exa-api-key-here" \\ + --name open-webui \\ + ghcr.io/open-webui/open-webui:main +``` + +## Verify the Integration + +Once you have configured the API key, you can test the integration by enabling the web search feature in a chat and asking a question that requires up-to-date information from the web. If the integration is successful, Open WebUI will use Exa AI to fetch search results and provide an informed response. diff --git a/docs/tutorials/web-search/jina.md b/docs/tutorials/web-search/jina.md index 0f36966c3f..461f514240 100644 --- a/docs/tutorials/web-search/jina.md +++ b/docs/tutorials/web-search/jina.md @@ -8,3 +8,87 @@ title: "Jina" This tutorial is a community contribution and is not supported by the Open WebUI team. It serves only as a demonstration on how to customize Open WebUI for your specific use case. Want to contribute? Check out the contributing tutorial. ::: + +# Jina Web Search Integration + +This guide provides instructions on how to integrate [Jina AI](https://jina.ai/), a powerful AI-driven search foundation, with Open WebUI. The integration uses Jina's `DeepSearch` API to provide web search capabilities. + +## Overview + +Jina AI's `DeepSearch` is more than a simple search API; it's an autonomous agent that combines web searching, reading, and reasoning to conduct comprehensive investigations. Unlike standard LLMs that rely on pre-trained knowledge or RAG systems that perform a single-pass search, DeepSearch iteratively searches, reads, and reasons, dynamically deciding its next steps based on its findings. It can perform deep dives into topics through multiple search and reasoning cycles and self-evaluates the quality of its answers before returning a result. + +:::tip OpenAI API Compatibility +The Jina DeepSearch API is fully compatible with the OpenAI Chat API schema. This means you can use it with any OpenAI-compatible client by simply swapping the API endpoint to `https://deepsearch.jina.ai/v1/chat/completions` and using `jina-deepsearch-v1` as the model name. +::: + +## Pricing and API Key + +Jina's `DeepSearch` API requires an API key for use with Open WebUI. Jina offers a free tier for new users, which includes **10 million tokens** to use with any of their models. You can obtain your free API key by creating an account on the Jina AI platform. + +- **API Key:** A Jina API key is required. You can get a key by logging into the [Jina API Dashboard](https://jina.ai/api-dashboard). + +## Configuration Steps + +### 1. Obtain a Jina API Key + +Follow these steps to get an API key: + +1. **Visit the Jina API Dashboard:** Go to [jina.ai/api-dashboard](https://jina.ai/api-dashboard). +2. **Log In or Sign Up:** Create a new account or log in to your existing one. +3. **Get Your API Key:** Once logged in, your unique API key will be displayed on the dashboard. Copy this key. + +### 2. Configure Open WebUI + +To enable the Jina web search integration, follow these steps in the Open WebUI admin settings: + +1. **Log in as an Administrator:** Access your Open WebUI instance and log in with an administrator account. +2. **Navigate to Web Search Settings:** Go to the **Admin Panel**, then click on **Settings** > **Web Search**. +3. **Select Jina as the Search Engine:** In the "Web Search Engine" dropdown menu, select **Jina**. +4. **Enter Your API Key:** Paste your Jina API key into the **Jina API Key** input field. +5. **Save Changes:** Scroll down and click the **Save** button to apply the changes. + +### 3. Environment Variable Configuration + +For Docker-based deployments, you can configure the Jina integration using an environment variable. + +Set the following environment variable for your Open WebUI instance: + +- `JINA_API_KEY`: Your Jina API key. + +**Example Docker `run` command:** + +```bash +docker run -d \\ + -p 3000:8080 \\ + -e JINA_API_KEY="your-jina-api-key-here" \\ + --name open-webui \\ + ghcr.io/open-webui/open-webui:main +``` + +## Advanced Configuration (Jina API) + +While Open WebUI provides a straightforward integration, the Jina DeepSearch API itself offers a rich set of parameters for fine-tuning its behavior. These parameters are part of the Jina API and are not directly exposed in the Open WebUI settings, but they are useful to understand for advanced use cases. + +### Quality Control + +You can control the trade-off between the quality of the results and token consumption using the following parameters: + +- **`reasoning_effort`**: A preset that adjusts `budget_tokens` and `max_attempts`. Options are `low`, `medium`, and `high`. This is the simplest way to control quality. +- **`budget_tokens`**: Sets the maximum number of tokens allowed for the entire DeepSearch process. Larger budgets can lead to better response quality. +- **`max_attempts`**: The number of times the system will retry to solve a problem. +- **`team_size`**: The number of agents that will work on the problem in parallel, allowing for broader research. + +### Source Control + +You can control where DeepSearch gets its information from: + +- **`no_direct_answer`**: Forces the system to always search the web, even for simple questions. +- **`boost_hostnames`**: A list of domains that are given a higher priority. +- **`bad_hostnames`**: A list of domains to be strictly excluded. +- **`only_hostnames`**: A list of domains to be exclusively included. + +For more details on these parameters, refer to the [official Jina DeepSearch documentation](https://jina.ai/deepsearch/). + +## Verify the Integration + +After configuring the settings, you can test the integration. Enable the web search feature in a chat and ask a question. Open WebUI will now use Jina's `DeepSearch` to retrieve and process web content to answer your query.