From 43ae2b98df4dce92c171dc1dc3aa97dd5967f0c2 Mon Sep 17 00:00:00 2001 From: Hendrik Hassa <65833107+HennieLP@users.noreply.github.com> Date: Tue, 2 Dec 2025 18:31:08 +0100 Subject: [PATCH 01/66] Adds document intelligence model configuration Adds the `DOCUMENT_INTELLIGENCE_MODEL` environment variable, allowing users to specify the model used for document intelligence. --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5dec0df04..475ba8390 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -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` From fbd240c0d4cc1d6e7f61e3a2acab625cb5d08886 Mon Sep 17 00:00:00 2001 From: bitsofinfo Date: Thu, 4 Dec 2025 15:02:57 -0700 Subject: [PATCH 02/66] feat: AUTH0_AUDIENCE --- docs/features/auth/sso/index.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/features/auth/sso/index.mdx b/docs/features/auth/sso/index.mdx index 72395c775..6965d8d04 100644 --- a/docs/features/auth/sso/index.mdx +++ b/docs/features/auth/sso/index.mdx @@ -121,6 +121,10 @@ The following environment variables are used: 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 `/oauth/oidc/callback`. +#### Auth0 + +1. `AUTH0_AUDIENCE`: If the OIDC provider is Auth0, this optional value can be set to the specific Auth0 `audience` the token should be issued for; doing so will ensure the access token is a JWT. If not specified the default behavior will be the issuance of an opaque Auth0 access token. [More info here](https://support.auth0.com/center/s/article/opaque-versus-jwt-access-token) + :::warning **Common OIDC Mistakes:** From c1cf8284ebc30594a9e231578b3146f26ed64816 Mon Sep 17 00:00:00 2001 From: bitsofinfo Date: Thu, 4 Dec 2025 16:20:00 -0700 Subject: [PATCH 03/66] feat: OAUTH_AUDIENCE config --- docs/features/auth/sso/index.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/features/auth/sso/index.mdx b/docs/features/auth/sso/index.mdx index 6965d8d04..0e7d9f748 100644 --- a/docs/features/auth/sso/index.mdx +++ b/docs/features/auth/sso/index.mdx @@ -120,10 +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 `/oauth/oidc/callback`. - -#### Auth0 - -1. `AUTH0_AUDIENCE`: If the OIDC provider is Auth0, this optional value can be set to the specific Auth0 `audience` the token should be issued for; doing so will ensure the access token is a JWT. If not specified the default behavior will be the issuance of an opaque Auth0 access token. [More info here](https://support.auth0.com/center/s/article/opaque-versus-jwt-access-token) +1. `OAUTH_AUDIENCE` - Optional `audience` value that will be passed to the oauth provider's authorization endpoint as an additional query parameter. :::warning From c6c50c497543833e5acaff21f5483436c2a9f697 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:27:15 +0100 Subject: [PATCH 04/66] Enhance env-configuration documentation for Redis Added documentation for Redis socket connection timeout and websocket Redis options. --- docs/getting-started/env-configuration.mdx | 43 ++++++++++++++++++++-- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5dec0df04..36788088e 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5118,6 +5118,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 +5230,24 @@ This option has no effect if `WEBSOCKET_SENTINEL_HOSTS` is defined. #### `WEBSOCKET_REDIS_OPTIONS` - Type: `str` -- Default: `{}` -- 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. +- 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 (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` From d14549c62e230a614c4f310d365d9bd7f4907b07 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:28:03 +0100 Subject: [PATCH 05/66] Update redis.md --- docs/tutorials/integrations/redis.md | 38 +++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/docs/tutorials/integrations/redis.md b/docs/tutorials/integrations/redis.md index 60bc7fef6..2e48e1daa 100644 --- a/docs/tutorials/integrations/redis.md +++ b/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: From fff5d6f45b8765497e0c4cc9706c364328378486 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Mon, 8 Dec 2025 23:43:22 +0100 Subject: [PATCH 06/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 29 +++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 36788088e..17587ca58 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/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. ::: @@ -3197,6 +3197,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 +4289,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` From 5e635a4fb7a4c0ef43f4d16ae8f628aca8d0c33b Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sun, 14 Dec 2025 18:45:40 +0100 Subject: [PATCH 07/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 9daa8e2c8..36fa2e4b6 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2889,6 +2889,13 @@ This environment variable was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". the search query. Example: `http://searxng.local/search?q=` - Persistence: This environment variable is a `PersistentConfig` variable. +#### `SEARXNG_LANGUAGE` + +- Type: `str` +- Default: `all` +- Description: This variable is used in the request to searxng as the "search language" (arguement "language"). +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `GOOGLE_PSE_API_KEY` - Type: `str` From 4142ff92fa683ec4edc9a63460e2fb4a0e6e8005 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Tue, 16 Dec 2025 11:25:30 +0100 Subject: [PATCH 08/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 36fa2e4b6..5fc17133b 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5210,8 +5210,8 @@ When deploying Open WebUI with `UVICORN_WORKERS > 1` or in a multi-node/worker c #### `WEBSOCKET_MANAGER` - Type: `str` -- Default: `redis` -- Description: Specifies the websocket manager to use (in this case, Redis). +- Default: `"" (empty string)` +- Description: Specifies the websocket manager to use. Allowed values include: `redis` :::warning From b1b0cf322dd1c69b610b3240fc404dbf599f65d3 Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:08:50 +0100 Subject: [PATCH 09/66] Add image tags information for production env in doc --- docs/getting-started/updating.mdx | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index bab079753..7c7be78be 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -57,6 +57,33 @@ Status: Downloaded newer image for ghcr.io/open-webui/open-webui:main Your chat histories, settings, and uploaded files are stored in a Docker volume named `open-webui`. Pulling a new image does **not** affect this data. The volume persists independently of the container. ::: +### (Optional) Using image tags in production + +Open WebUI provides multiple Docker image tags depending on how you want to manage updates. + +If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup. + +Examples (latest version tags): +``` +ghcr.io/open-webui/open-webui:main +ghcr.io/open-webui/open-webui:cuda +ghcr.io/open-webui/open-webui:ollama +``` + +For `production environments` where stability and reproducibility are important, it is recommended to pin a specific release version instead of using these floating tags. + +Versioned images follow this format: +``` +ghcr.io/open-webui/open-webui:- +``` + +Examples (pinned versions — replace with the release version you want to use): +``` +ghcr.io/open-webui/open-webui:v0.6.41 +ghcr.io/open-webui/open-webui:v0.6.41-cuda +ghcr.io/open-webui/open-webui:v0.6.41-ollama +``` + ### Step 3: Start Container with Updated Image Recreate the container using the new image while mounting your existing data volume. From f34a32bc15b41756eeb1c0d71ecee85bc159ce7d Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:10:01 +0100 Subject: [PATCH 10/66] Remove useless line --- docs/getting-started/updating.mdx | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 7c7be78be..422f25337 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -60,7 +60,6 @@ Your chat histories, settings, and uploaded files are stored in a Docker volume ### (Optional) Using image tags in production Open WebUI provides multiple Docker image tags depending on how you want to manage updates. - If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup. Examples (latest version tags): From 39834100fb3465d0f87e461751598bcdbf0b9d4c Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:14:12 +0100 Subject: [PATCH 11/66] Mention pulling a specific Open WebUI version --- .../quick-start/tab-docker/ManualDocker.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index 9ceacfe8f..167a69973 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -18,6 +18,14 @@ For environments with limited storage or bandwidth, Open WebUI offers slim image docker pull ghcr.io/open-webui/open-webui:main-slim ``` +### Specific release version + +You can also pull a specific Open WebUI release version directly by using a versioned image tag. This is recommended for production environments to ensure stable and reproducible deployments. + +```bash +docker pull ghcr.io/open-webui/open-webui:v0.6.41 +``` + ## Step 2: Run the Container Run the container with default settings. This command includes a volume mapping to ensure persistent data storage. From 6cdbfdac3be548f34fc11ee36b3ec4f33e58da96 Mon Sep 17 00:00:00 2001 From: alicanyuksel Date: Fri, 19 Dec 2025 00:20:28 +0100 Subject: [PATCH 12/66] Add image tags explication in homepage --- docs/intro.mdx | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/intro.mdx b/docs/intro.mdx index 72ce9a263..8b447c1e8 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -89,6 +89,22 @@ Both commands facilitate a built-in, hassle-free installation of both Open WebUI After installation, you can access Open WebUI at [http://localhost:3000](http://localhost:3000). Enjoy! 😄 +### Using image tags in production + +If you want to always run the latest version of Open WebUI, you can use the `:main`, `:cuda`, or `:ollama` image tags, depending on your setup, as shown in the examples above. +For `production environments` where stability and reproducibility are important, it is recommended to pin a specific release version instead of using these floating tags. Versioned images follow this format: + +``` +ghcr.io/open-webui/open-webui:- +``` + +Examples (pinned versions for illustration purposes only): +``` +ghcr.io/open-webui/open-webui:v0.6.41 +ghcr.io/open-webui/open-webui:v0.6.41-ollama +ghcr.io/open-webui/open-webui:v0.6.41-cuda +``` + ### Using the Dev Branch 🌙 :::warning From fd39c970669c82a03a2671cb9ea10e19f6d37c28 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 14:28:46 +0100 Subject: [PATCH 13/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5fc17133b..5ec2faefb 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -225,6 +225,13 @@ This caches the external model lists retrieved from configured OpenAI-compatible - Description: Toggles whether to show admin user details in the interface. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_PUBLIC_ACTIVE_USERS_COUNT` + +- Type: `bool` +- Default: `True` +- Description: Controls whether the active user count is visible to all users or restricted to administrators only. When set to `False`, only admin users can see how many users are currently active, reducing backend load and addressing privacy concerns in large deployments. +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `ADMIN_EMAIL` - Type: `str` From ebf7f165017fbf858c4432af72c74e90c577b3ab Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 14:42:34 +0100 Subject: [PATCH 14/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 5ec2faefb..cf3f7e85d 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2138,6 +2138,7 @@ Note: this configuration assumes that AWS credentials will be available to your - `docling` - Use Docling engine - `document_intelligence` - Use Document Intelligence engine - `mistral_ocr` - Use Mistral OCR engine + - `mineru` - Description: Sets the content extraction engine to use for document ingestion. - Persistence: This environment variable is a `PersistentConfig` variable. @@ -2270,6 +2271,13 @@ DOCLING_PARAMS="{\"do_ocr\": true, \"ocr_engine\": \"tesseract\", \"ocr_lang\": ::: +#### `MINERU_API_TIMEOUT` + +- Type: `str` +- Default: `300` +- Description: Sets the timeout in seconds for MinerU API requests during document processing. +- Persistence: This environment variable is a `PersistentConfig` variable. + ## Retrieval Augmented Generation (RAG) ### Core Configuration From ba9c6120ed41d123f0deff4567c8b4660ec05350 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 14:47:41 +0100 Subject: [PATCH 15/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index cf3f7e85d..f4b032cf1 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2593,6 +2593,13 @@ If you are embedding externally via API, ensure your rate limits are high enough - Description: Sets a model for reranking results. Locally, a Sentence-Transformer model is used. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `RAG_EXTERNAL_RERANKER_TIMEOUT` + +- Type: `str` +- Default: Empty string (' ') +- Description: Sets the timeout in seconds for external reranker API requests during RAG document retrieval. Leave empty to use default timeout behavior. +- Persistence: This environment variable is a `PersistentConfig` variable. + ### Query Generation #### `ENABLE_RETRIEVAL_QUERY_GENERATION` From 3f25401b0eaeadbf5dbb60c778a7458bf3baa254 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 17:30:54 +0100 Subject: [PATCH 16/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index f4b032cf1..521538d1d 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5044,10 +5044,21 @@ When `DATABASE_URL` is not explicitly set, Open WebUI will attempt to construct For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed. +:::warning Additional Dependencies Required + +SQLCipher encryption requires additional dependencies that are **not included by default**. Before using this feature, you must install: + +- The **SQLCipher system library** (e.g., `libsqlcipher-dev` on Debian/Ubuntu, `sqlcipher` on macOS via Homebrew) +- The **`sqlcipher3-wheels`** Python package (`pip install sqlcipher3-wheels`) + +For Docker users, this means building a custom image with these dependencies included. + +::: + To enable encryption, you must configure two environment variables: 1. Set `DATABASE_TYPE="sqlite+sqlcipher"`. -1. Set `DATABASE_PASSWORD="your-secure-password"`. +2. Set `DATABASE_PASSWORD="your-secure-password"`. When these are set and a full `DATABASE_URL` is **not** explicitly defined, Open WebUI will automatically create and use an encrypted database file at `./data/webui.db`. From dd29bae504205602e17e3363866fff74bd95465b Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 17:34:08 +0100 Subject: [PATCH 17/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 521538d1d..bbb341fd4 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2609,6 +2609,12 @@ If you are embedding externally via API, ensure your rate limits are high enough - Description: Enables or disables retrieval query generation. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `ENABLE_QUERIES_CACHE` + +- Type: `bool` +- Default: `False` +- Description: Enables request-scoped caching of LLM-generated search queries. When enabled, queries generated for web search are **cached** and automatically **reused** for file/knowledge base retrieval within the same request. This **eliminates duplicate LLM calls** when both web search and RAG are active, **reducing token usage and latency** while maintaining search quality. It is highly recommended to enable this especially in larger setups. + #### `QUERY_GENERATION_PROMPT_TEMPLATE` - Type: `str` @@ -5034,12 +5040,6 @@ When `DATABASE_URL` is not explicitly set, Open WebUI will attempt to construct - Default: `None` - Description: Sets the minimum time interval in seconds between user active status updates in the database. Helps reduce write operations for high-traffic instances. Set to `0.0` to update on every activity. -#### `ENABLE_QUERIES_CACHE` - -- Type: `bool` -- Default: `False` -- Description: Enables query result caching to improve database performance by storing and reusing frequently accessed data. - ### Encrypted SQLite with SQLCipher For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed. From c12467008768ffb8fe6f8277c9f26d5018684254 Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:20:07 +0100 Subject: [PATCH 18/66] Update ManualDocker.md --- docs/getting-started/quick-start/tab-docker/ManualDocker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index 167a69973..bfd2c51ec 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -23,7 +23,7 @@ docker pull ghcr.io/open-webui/open-webui:main-slim You can also pull a specific Open WebUI release version directly by using a versioned image tag. This is recommended for production environments to ensure stable and reproducible deployments. ```bash -docker pull ghcr.io/open-webui/open-webui:v0.6.41 +docker pull ghcr.io/open-webui/open-webui:v0.6.42 ``` ## Step 2: Run the Container From 7162a1fbaaf58d0af8c62f9cb214e2ce1c53271f Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:20:28 +0100 Subject: [PATCH 19/66] Update updating.mdx --- docs/getting-started/updating.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 422f25337..134862f03 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -78,9 +78,9 @@ ghcr.io/open-webui/open-webui:- Examples (pinned versions — replace with the release version you want to use): ``` -ghcr.io/open-webui/open-webui:v0.6.41 -ghcr.io/open-webui/open-webui:v0.6.41-cuda -ghcr.io/open-webui/open-webui:v0.6.41-ollama +ghcr.io/open-webui/open-webui:v0.6.52 +ghcr.io/open-webui/open-webui:v0.6.52-cuda +ghcr.io/open-webui/open-webui:v0.6.52-ollama ``` ### Step 3: Start Container with Updated Image From 6c9a48d8e8376e5903d3ee97d1df9662753ae0cd Mon Sep 17 00:00:00 2001 From: Classic298 <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:20:53 +0100 Subject: [PATCH 20/66] Update intro.mdx --- docs/intro.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/intro.mdx b/docs/intro.mdx index 8b447c1e8..7b4fd700c 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -100,9 +100,9 @@ ghcr.io/open-webui/open-webui:- Examples (pinned versions for illustration purposes only): ``` -ghcr.io/open-webui/open-webui:v0.6.41 -ghcr.io/open-webui/open-webui:v0.6.41-ollama -ghcr.io/open-webui/open-webui:v0.6.41-cuda +ghcr.io/open-webui/open-webui:v0.6.42 +ghcr.io/open-webui/open-webui:v0.6.42-ollama +ghcr.io/open-webui/open-webui:v0.6.42-cuda ``` ### Using the Dev Branch 🌙 From 5cf87a0036cee7237e55daac554da4a2aa3cb19f Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:21:21 +0100 Subject: [PATCH 21/66] update various docs --- docs/features/channels/index.md | 79 +++++++-- docs/features/notes.md | 22 ++- docs/tutorials/maintenance/backups.md | 2 +- docs/tutorials/maintenance/database.mdx | 9 +- .../tips/improve-performance-local.md | 117 ++++++++++++- docs/tutorials/tips/reduce-ram-usage.md | 165 ++++++++++++++++-- docs/tutorials/tips/sqlite-database.md | 156 ++++++++++++++--- 7 files changed, 496 insertions(+), 54 deletions(-) diff --git a/docs/features/channels/index.md b/docs/features/channels/index.md index e1b3e8cad..ef0d7a439 100644 --- a/docs/features/channels/index.md +++ b/docs/features/channels/index.md @@ -9,6 +9,35 @@ title: "Channels" Channels is currently a **Beta** feature. Functionality is subject to change, and it must be explicitly enabled by an Administrator before it appears in the interface. ::: +## Channel Types + +Open WebUI supports three types of channels: + +| Type | Description | +|------|-------------| +| **Standard** | Traditional topic-based channels with public or private visibility | +| **Group** | Membership-based channels where users explicitly join as members | +| **Direct Message** | Private one-on-one or multi-user conversations | + +### Group Channels + +Group channels are collaboration spaces where: +- Users explicitly join as members rather than accessing through permissions +- Support public or private visibility +- Can automatically include members from specified user groups +- Channel managers can add or remove members through the channel info modal + +### Direct Message Channels + +Direct Message (DM) channels enable private conversations: +- One-on-one or multi-user private messaging +- Automatic deduplication for existing conversations +- Optional channel naming +- Display participant avatars instead of channel icons +- Can be hidden from sidebar while preserving message history +- Automatically reappear when new messages arrive +- Show online/offline status indicator for participants + ## Enabling Channels By default, the Channels feature may be hidden. An **Admin** must enable it globally for the instance. @@ -22,12 +51,19 @@ By default, the Channels feature may be hidden. An **Admin** must enable it glob ## Creating a Channel +:::note +Channel creation is restricted to administrators only by default. +::: + 1. Locate the **Channels** header in the sidebar. 2. Click the **(+) Plus** icon next to the "Channels" header. -3. **Name:** Enter a channel name (e.g., `general`, `python-dev`). Spaces should get converted to hyphens. -4. **Access Control:** - * **Public:** All registered users on your Open WebUI instance can see and join this channel. - * **Private/Group Access:** Only you or users with permission can access this channel. +3. **Select Channel Type:** Choose Standard, Group, or Direct Message. +4. **Name:** Enter a channel name (e.g., `general`, `python-dev`). Spaces are converted to hyphens. +5. **Access Control:** + * **Public:** All registered users can see and join this channel. + * **Private/Group Access:** Only you or users with permission can access. + * For Group channels, select which user groups to auto-include. + * For DM channels, use the user selection interface to choose participants. ## Using Channels @@ -79,22 +115,33 @@ If a user **does not** have access to view a linked channel (e.g., `#admin-only` Hover over any message in the timeline to access interaction options: -* **Add Reaction:** Click the **Smiley Face** icon to add a visual emoji eaction to a message. -* **Reply:** Quotes the message within the main channel stream, linking your response to the original message while keeping it visible to everyone in the main flow. -* **Reply in Thread:** Starts a separate, nested conversation thread centered on that specific message. This allows for focused discussions without cluttering the main channel history. -* **Edit:** Click the **Pencil** icon to modify the content of your message. -* **Delete:** Click the **Trash** icon to remove the message from the channel. +* **Add Reaction:** Click the **Smiley Face** icon to add an emoji reaction. Hovering over reactions shows the names of users who reacted (up to 3 names plus a count for additional reactors). +* **Pin Message:** Pin important messages for easy reference. Pinned messages are highlighted and accessible via a dedicated modal in the navbar. +* **Reply:** Quotes the message within the main channel stream. +* **Reply in Thread:** Starts a separate, nested conversation thread. +* **Edit:** Click the **Pencil** icon to modify your message. +* **Delete:** Click the **Trash** icon to remove the message. :::note Currently, reactions are purely visual and do not influence model behavior. ::: +### File Attachments + +Channels support file sharing: + +* **Paste from clipboard:** Images and files can be pasted directly using Ctrl+V / Cmd+V +* **Drag and drop:** Drag files directly into the message input +* **Image processing:** AI models in channels can view and analyze shared images + ### Collaboration If your Open WebUI instance supports multiple users: -* **Real-time updates:** Messages appear instantly for all users currently viewing the channel. -* **Shared Context:** When a teammate asks an AI a question, the AI's response becomes part of the context for the *next* user's query. This allows teams to iterate on AI outputs together. +* **Real-time updates:** Messages appear instantly using optimistic UI rendering. +* **Shared Context:** AI responses become part of the context for subsequent queries. +* **Unread indicators:** Visual badges show unread message counts in the sidebar. +* **User list:** Click to view all users with access to the channel. ## Managing Channels @@ -106,9 +153,17 @@ To manage an existing channel: 2. Click the **Gear (Edit)** icon. :::info -Only the Channel Creator or an Admin can delete a channel. +Channel creators can edit and delete their own group and DM channels without administrator privileges. Standard channels require admin access. ::: +### Permissions + +Channels support granular access control: + +* **Write access:** Required for posting, editing, and deleting messages +* **Read-only access:** Users can view content but cannot contribute +* **Feature toggle:** Administrators can control channel access via `USER_PERMISSIONS_FEATURES_CHANNELS` environment variable or group permissions in the admin panel + ## Use Cases ### 1. Team Development (`#dev-team`) diff --git a/docs/features/notes.md b/docs/features/notes.md index 1bc77d3fd..c8f60d314 100644 --- a/docs/features/notes.md +++ b/docs/features/notes.md @@ -24,6 +24,10 @@ Notes utilizes a context-aware **Floating Toolbar** for formatting, rather than * **Styling:** **Bold**, *Italic*, Underline, and ~~Strikethrough~~. * **Code:** Inline code formatting ``. +### Drag-and-Drop List Reordering + +List items can be reordered by dragging. Visual drag handles appear when hovering over list items, making it easy to reorganize content. + While this toolbar is native to the Notes workspace, it can also be enabled for standard Chats. :::info To see this toolbar in your main chat input: @@ -100,7 +104,7 @@ You can export your notes in standard formats: * **Plain text (.txt):** The raw text content. * **Plain text (.md):** Preserves Markdown structure (headers, code blocks, etc.). -* **PDF document (.pdf):** A rendered document with visual formatting applied. +* **PDF document (.pdf):** A rendered document with visual formatting applied. Dark mode styling is automatically detected and applied. ### Sharing @@ -114,6 +118,22 @@ You can delete notes permanently from two locations: 1. **From the Notes Dashboard:** Click the **More (`...`)** button on the individual note card in the list view and select **Delete**. 2. **From the Editor:** While inside an open note, click the **More (`...`)** button in the top right corner of the screen and select **Delete**. +### Sharing Permissions + +Administrators can control whether users are allowed to share notes publicly: + +* **Environment Variable:** `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING` +* **Admin Panel:** Settings > Users > Default Permissions + +### Quick Note Creation via URL + +Notes can be created directly by navigating to `/notes/new` with optional query parameters: + +* `/notes/new` — Opens a blank note +* `/notes/new?title=My%20Title&content=Initial%20text` — Pre-populates title and content + +This enables bookmarks and shortcuts for fast note creation. + --- ## Use Cases diff --git a/docs/tutorials/maintenance/backups.md b/docs/tutorials/maintenance/backups.md index e146af251..e0ba345c7 100644 --- a/docs/tutorials/maintenance/backups.md +++ b/docs/tutorials/maintenance/backups.md @@ -403,7 +403,7 @@ In the interest of keeping this guide reasonably thorough these additional subje | Topic | Description | |---|---| | SQLite Built-in Backup | Consider using SQLite's `.backup` command for a consistent database backup solution. | -| Encryption | Modify backup scripts to incorporate encryption at rest for enhanced security. | +| Encryption | Modify backup scripts to incorporate encryption at rest. See [Database Encryption with SQLCipher](/tutorials/tips/sqlite-database#database-encryption-with-sqlcipher) for database-level encryption. | | Disaster Recovery and Testing | Develop a disaster recovery plan and regularly test the backup and restore process. | | Alternative Backup Tools | Explore other command-line backup tools like `borgbackup` or `restic` for advanced features. | | Email Notifications and Webhooks | Implement email notifications or webhooks to monitor backup success or failure. | diff --git a/docs/tutorials/maintenance/database.mdx b/docs/tutorials/maintenance/database.mdx index 68455aeb9..598c36565 100644 --- a/docs/tutorials/maintenance/database.mdx +++ b/docs/tutorials/maintenance/database.mdx @@ -93,4 +93,11 @@ docker cp ./webui.db open-webui:/app/backend/data/webui.db docker start open-webui ``` -With these steps, you can easily manage your Open WebUI migration or backup process. Keep in mind the database format you're using to ensure compatibility. \ No newline at end of file +With these steps, you can easily manage your Open WebUI migration or backup process. Keep in mind the database format you're using to ensure compatibility. + +--- + +## Related Guides + +- [SQLite Database Overview](/tutorials/tips/sqlite-database) - Detailed database schema and SQLCipher encryption setup +- [Backups](/tutorials/maintenance/backups) - Comprehensive backup strategies for your instance diff --git a/docs/tutorials/tips/improve-performance-local.md b/docs/tutorials/tips/improve-performance-local.md index 4bb8a7596..dc1c6b047 100644 --- a/docs/tutorials/tips/improve-performance-local.md +++ b/docs/tutorials/tips/improve-performance-local.md @@ -15,16 +15,16 @@ This guide explains how to optimize your setup by configuring a dedicated, light ## Why Does Open-WebUI Feel Slow? -By default, Open-WebUI has several background tasks that can make it feel like magic but can also place a eavy load on local resources: +By default, Open-WebUI has several background tasks that can make it feel like magic but can also place a heavy load on local resources: - **Title Generation** - **Tag Generation** - **Autocomplete Generation** (this function triggers on every keystroke) - **Search Query Generation** -Each of these features makes asynchronous requests to your model. For example, continuous calls from the utocomplete feature can significantly delay responses on devices with limited memory >or processing power, uch as a Mac with 32GB of RAM running a 32B quantized model. +Each of these features makes asynchronous requests to your model. For example, continuous calls from the autocomplete feature can significantly delay responses on devices with limited memory or processing power, such as a Mac with 32GB of RAM running a 32B quantized model. -Optimizing the task model can help isolate these background tasks from your main chat application, improving verall responsiveness. +Optimizing the task model can help isolate these background tasks from your main chat application, improving overall responsiveness. ::: @@ -78,6 +78,109 @@ Implementing these recommendations can greatly improve the responsiveness of Ope --- +## ⚙️ Environment Variables for Performance + +You can also configure performance-related settings via environment variables. Add these to your Docker Compose file or `.env` file. + +:::tip + +Many of these settings can also be configured directly in the **Admin Panel > Settings** interface. Environment variables are useful for initial deployment configuration or when managing settings across multiple instances. + +::: + +### Task Model Configuration + +Set a dedicated lightweight model for background tasks: + +```bash +TASK_MODEL=llama3.2:3b + +# For OpenAI-compatible endpoints +TASK_MODEL_EXTERNAL=gpt-4o-mini +``` + +### Disable Unnecessary Features + +```bash +# Disable automatic title generation +ENABLE_TITLE_GENERATION=False + +# Disable follow-up question suggestions +ENABLE_FOLLOW_UP_GENERATION=False + +# Disable autocomplete suggestions (triggers on every keystroke - high impact!) +ENABLE_AUTOCOMPLETE_GENERATION=False + +# Disable automatic tag generation +ENABLE_TAGS_GENERATION=False + +# Disable search query generation for RAG (if not using web search) +ENABLE_SEARCH_QUERY_GENERATION=False + +# Disable retrieval query generation +ENABLE_RETRIEVAL_QUERY_GENERATION=False +``` + +### Enable Caching and Optimization + +```bash +# Cache model list responses (seconds) - reduces API calls +MODELS_CACHE_TTL=300 + +# Cache LLM-generated search queries - eliminates duplicate LLM calls when both web search and RAG are active +ENABLE_QUERIES_CACHE=True + +# Convert base64 images to file URLs - reduces response size and database strain +ENABLE_CHAT_RESPONSE_BASE64_IMAGE_URL_CONVERSION=True + +# Batch streaming tokens to reduce CPU load (recommended: 5-10 for high concurrency) +CHAT_RESPONSE_STREAM_DELTA_CHUNK_SIZE=5 + +# Enable gzip compression for HTTP responses (enabled by default) +ENABLE_COMPRESSION_MIDDLEWARE=True +``` + +### Database and Persistence + +```bash +# Disable real-time chat saving for better performance (trades off data persistence) +ENABLE_REALTIME_CHAT_SAVE=False +``` + +### Network Timeouts + +```bash +# Increase timeout for slow models (default: 300 seconds) +AIOHTTP_CLIENT_TIMEOUT=300 + +# Faster timeout for model list fetching (default: 10 seconds) +AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST=5 +``` + +### RAG Performance + +```bash +# Enable parallel embedding for faster document processing (requires sufficient resources) +RAG_EMBEDDING_BATCH_SIZE=100 +``` + +### High Concurrency Settings + +For larger instances with many concurrent users: + +```bash +# Increase thread pool size (default is 40) +THREAD_POOL_SIZE=500 +``` + +:::info + +For a complete list of environment variables, see the [Environment Variable Configuration](/getting-started/env-configuration) documentation. + +::: + +--- + ## 💡 Additional Tips - **Monitor System Resources:** Use your operating system’s tools (such as Activity Monitor on macOS or Task Manager on Windows) to keep an eye on resource usage. @@ -87,4 +190,12 @@ Implementing these recommendations can greatly improve the responsiveness of Ope --- +## Related Guides + +- [Reduce RAM Usage](/tutorials/tips/reduce-ram-usage) - For memory-constrained environments like Raspberry Pi +- [SQLite Database Overview](/tutorials/tips/sqlite-database) - Database schema, encryption, and advanced configuration +- [Environment Variable Configuration](/getting-started/env-configuration) - Complete list of all configuration options + +--- + By applying these configuration changes, you'll support a more responsive and efficient Open-WebUI experience, allowing your local LLM to focus on delivering high-quality chat interactions without unnecessary delays. diff --git a/docs/tutorials/tips/reduce-ram-usage.md b/docs/tutorials/tips/reduce-ram-usage.md index 01a6cd564..769007b23 100644 --- a/docs/tutorials/tips/reduce-ram-usage.md +++ b/docs/tutorials/tips/reduce-ram-usage.md @@ -5,23 +5,164 @@ title: "Reduce RAM Usage" ## Reduce RAM Usage -If you are deploying this image in a RAM-constrained environment, there are a few things you can do to slim down the image. +If you are deploying Open WebUI in a RAM-constrained environment (such as a Raspberry Pi, small VPS, or shared hosting), there are several strategies to significantly reduce memory consumption. -On a Raspberry Pi 4 (arm64) with version v0.3.10, this was able to reduce idle memory consumption from >1GB to ~200MB (as observed with `docker container stats`). +On a Raspberry Pi 4 (arm64) with version v0.3.10, these optimizations reduced idle memory consumption from >1GB to ~200MB (as observed with `docker container stats`). -## TLDR +--- + +## Quick Start + +Set the following environment variables for immediate RAM savings: + +```bash +# Use external embedding instead of local SentenceTransformers +RAG_EMBEDDING_ENGINE=ollama + +# Use external Speech-to-Text instead of local Whisper +AUDIO_STT_ENGINE=openai +``` + +:::tip + +These settings can also be configured in the **Admin Panel > Settings** interface - set RAG embedding to Ollama or OpenAI, and Speech-to-Text to OpenAI or WebAPI. + +::: + +--- + +## Why Does Open WebUI Use So Much RAM? + +Much of the memory consumption comes from locally loaded ML models. Even when using an external LLM (OpenAI or separate Ollama instance), Open WebUI may load additional models for: + +| Feature | Default | RAM Impact | Solution | +|---------|---------|------------|----------| +| **RAG Embedding** | Local SentenceTransformers | ~500-800MB | Use Ollama or OpenAI embeddings | +| **Speech-to-Text** | Local Whisper | ~300-500MB | Use OpenAI or WebAPI | +| **Reranking** | Disabled | ~200-400MB when enabled | Keep disabled or use external | +| **Image Generation** | Disabled | Variable | Keep disabled if not needed | + +--- + +## ⚙️ Environment Variables for RAM Reduction + +### Offload Embedding to External Service + +The biggest RAM saver is using an external embedding engine: + +```bash +# Option 1: Use Ollama for embeddings (if you have Ollama running separately) +RAG_EMBEDDING_ENGINE=ollama + +# Option 2: Use OpenAI for embeddings +RAG_EMBEDDING_ENGINE=openai +OPENAI_API_KEY=your-api-key +``` + +### Offload Speech-to-Text + +Local Whisper models consume significant RAM: + +```bash +# Use OpenAI's Whisper API +AUDIO_STT_ENGINE=openai + +# Or use browser-based WebAPI (no external service needed) +AUDIO_STT_ENGINE=webapi +``` + +### Disable Unused Features + +Disable features you don't need to prevent model loading: -Set the following environment variables (or the respective UI settings for an existing deployment): `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`. +```bash +# Disable image generation (prevents loading image models) +ENABLE_IMAGE_GENERATION=False -## Longer explanation +# Disable code execution (reduces overhead) +ENABLE_CODE_EXECUTION=False -Much of the memory consumption is due to loaded ML models. Even if you are using an external language model (OpenAI or unbundled ollama), many models may be loaded for additional purposes. +# Disable code interpreter +ENABLE_CODE_INTERPRETER=False +``` + +### Reduce Background Task Overhead + +These settings reduce memory usage from background operations: + +```bash +# Disable autocomplete (high resource usage) +ENABLE_AUTOCOMPLETE_GENERATION=False + +# Disable automatic title generation +ENABLE_TITLE_GENERATION=False + +# Disable tag generation +ENABLE_TAGS_GENERATION=False + +# Disable follow-up suggestions +ENABLE_FOLLOW_UP_GENERATION=False +``` + +### Database and Cache Optimization + +```bash +# Disable real-time chat saving (reduces database overhead) +ENABLE_REALTIME_CHAT_SAVE=False + +# Reduce thread pool size for low-resource systems +THREAD_POOL_SIZE=10 +``` + +### Vector Database Multitenancy + +If using Milvus or Qdrant, enable multitenancy mode to reduce RAM: + +```bash +# For Milvus +ENABLE_MILVUS_MULTITENANCY_MODE=True + +# For Qdrant +ENABLE_QDRANT_MULTITENANCY_MODE=True +``` + +--- + +## 🚀 Recommended Minimal Configuration + +For extremely RAM-constrained environments, use this combined configuration: + +```bash +# Offload ML models to external services +RAG_EMBEDDING_ENGINE=ollama +AUDIO_STT_ENGINE=openai + +# Disable all non-essential features +ENABLE_IMAGE_GENERATION=False +ENABLE_CODE_EXECUTION=False +ENABLE_CODE_INTERPRETER=False +ENABLE_AUTOCOMPLETE_GENERATION=False +ENABLE_TITLE_GENERATION=False +ENABLE_TAGS_GENERATION=False +ENABLE_FOLLOW_UP_GENERATION=False + +# Reduce worker overhead +THREAD_POOL_SIZE=10 +``` + +--- + +## 💡 Additional Tips + +- **Monitor Memory Usage**: Use `docker container stats` or `htop` to monitor RAM consumption +- **Restart After Changes**: Environment variable changes require a container restart +- **Fresh Deployments**: Some environment variables only take effect on fresh deployments without an existing `config.json` +- **Consider Alternatives**: For very constrained systems, consider running Open WebUI on a more capable machine and accessing it remotely + +--- -As of v0.3.10 this includes: +## Related Guides -- Speech-to-text (whisper by default) -- RAG embedding engine (defaults to local SentenceTransformers model) -- Image generation engine (disabled by default) +- [Improve Local LLM Performance](/tutorials/tips/improve-performance-local) - For optimizing performance without reducing features +- [Environment Variable Configuration](/getting-started/env-configuration) - Complete list of all configuration options -The first 2 are enabled and set to local models by default. You can change the models in the admin panel (RAG: Documents category, set it to Ollama or OpenAI, Speech-to-text: Audio section, work with OpenAI or WebAPI). -If you are deploying a fresh Docker image, you can also set them with the following environment variables: `RAG_EMBEDDING_ENGINE: ollama`, `AUDIO_STT_ENGINE: openai`. Note that these environment variables have no effect if a `config.json` already exists. diff --git a/docs/tutorials/tips/sqlite-database.md b/docs/tutorials/tips/sqlite-database.md index 6b3cb466d..32dae7b78 100644 --- a/docs/tutorials/tips/sqlite-database.md +++ b/docs/tutorials/tips/sqlite-database.md @@ -10,7 +10,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: > [!WARNING] -> This documentation was created/updated based on version 0.6.30. +> This documentation was created/updated based on version 0.6.41 and updated for recent migrations. ## Open-WebUI Internal SQLite Database @@ -56,28 +56,31 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar | ------- | ---------------- | ------------------------------------------------------------ | | 01 | auth | Stores user authentication credentials and login information | | 02 | channel | Manages chat channels and their configurations | -| 03 | channel_member | Tracks user membership and permissions within channels | -| 04 | chat | Stores chat sessions and their metadata | -| 05 | chatidtag | Maps relationships between chats and their associated tags | -| 06 | config | Maintains system-wide configuration settings | -| 07 | document | Stores documents and their metadata for knowledge management | -| 08 | feedback | Captures user feedback and ratings | -| 09 | file | Manages uploaded files and their metadata | -| 10 | folder | Organizes files and content into hierarchical structures | -| 11 | function | Stores custom functions and their configurations | -| 12 | group | Manages user groups and their permissions | -| 13 | knowledge | Stores knowledge base entries and related information | -| 14 | memory | Maintains chat history and context memory | -| 15 | message | Stores individual chat messages and their content | -| 16 | message_reaction | Records user reactions (emojis/responses) to messages | -| 17 | migrate_history | Tracks database schema version and migration records | -| 18 | model | Manages AI model configurations and settings | -| 19 | note | Stores user-created notes and annotations | -| 20 | oauth_session | Manages active OAuth sessions for users | -| 21 | prompt | Stores templates and configurations for AI prompts | -| 22 | tag | Manages tags/labels for content categorization | -| 23 | tool | Stores configurations for system tools and integrations | -| 24 | user | Maintains user profiles and account information | +| 03 | channel_file | Links files to channels and messages | +| 04 | channel_member | Tracks user membership and permissions within channels | +| 05 | chat | Stores chat sessions and their metadata | +| 06 | chatidtag | Maps relationships between chats and their associated tags | +| 07 | config | Maintains system-wide configuration settings | +| 08 | document | Stores documents and their metadata for knowledge management | +| 09 | feedback | Captures user feedback and ratings | +| 10 | file | Manages uploaded files and their metadata | +| 11 | folder | Organizes files and content into hierarchical structures | +| 12 | function | Stores custom functions and their configurations | +| 13 | group | Manages user groups and their permissions | +| 14 | group_member | Tracks user membership within groups | +| 15 | knowledge | Stores knowledge base entries and related information | +| 16 | knowledge_file | Links files to knowledge bases | +| 17 | memory | Maintains chat history and context memory | +| 18 | message | Stores individual chat messages and their content | +| 19 | message_reaction | Records user reactions (emojis/responses) to messages | +| 20 | migrate_history | Tracks database schema version and migration records | +| 21 | model | Manages AI model configurations and settings | +| 22 | note | Stores user-created notes and annotations | +| 23 | oauth_session | Manages active OAuth sessions for users | +| 24 | prompt | Stores templates and configurations for AI prompts | +| 25 | tag | Manages tags/labels for content categorization | +| 26 | tool | Stores configurations for system tools and integrations | +| 27 | user | Maintains user profiles and account information | Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded: @@ -129,6 +132,24 @@ Things to know about the auth table: | user_id | TEXT | NOT NULL | Reference to the user | | created_at | BIGINT | - | Timestamp when membership was created | +## Channel File Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | ---------------------------------- | --------------------------------- | +| id | Text | PRIMARY KEY | Unique identifier (UUID) | +| user_id | Text | NOT NULL | Owner of the relationship | +| channel_id | Text | FOREIGN KEY(channel.id), NOT NULL | Reference to the channel | +| file_id | Text | FOREIGN KEY(file.id), NOT NULL | Reference to the file | +| message_id | Text | FOREIGN KEY(message.id), nullable | Reference to associated message | +| created_at | BigInteger | NOT NULL | Creation timestamp | +| updated_at | BigInteger | NOT NULL | Last update timestamp | + +Things to know about the channel_file table: + +- Unique constraint on (`channel_id`, `file_id`) to prevent duplicate entries +- Foreign key relationships with CASCADE delete +- Indexed on `channel_id`, `file_id`, and `user_id` for performance + ## Chat Table | **Column Name** | **Data Type** | **Constraints** | **Description** | @@ -258,10 +279,26 @@ Things to know about the function table: | data | JSON | nullable | Additional group data | | meta | JSON | nullable | Group metadata | | permissions | JSON | nullable | Permission configuration | -| user_ids | JSON | nullable | List of member user IDs | | created_at | BigInteger | - | Creation timestamp | | updated_at | BigInteger | - | Last update timestamp | +Note: The `user_ids` column has been migrated to the `group_member` table. + +## Group Member Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | -------------------------------- | --------------------------------- | +| id | Text | PRIMARY KEY, UNIQUE | Unique identifier (UUID) | +| group_id | Text | FOREIGN KEY(group.id), NOT NULL | Reference to the group | +| user_id | Text | FOREIGN KEY(user.id), NOT NULL | Reference to the user | +| created_at | BigInteger | nullable | Creation timestamp | +| updated_at | BigInteger | nullable | Last update timestamp | + +Things to know about the group_member table: + +- Unique constraint on (`group_id`, `user_id`) to prevent duplicate memberships +- Foreign key relationships with CASCADE delete to group and user tables + ## Knowledge Table | **Column Name** | **Data Type** | **Constraints** | **Description** | @@ -276,6 +313,23 @@ Things to know about the function table: | created_at | BigInteger | - | Creation timestamp | | updated_at | BigInteger | - | Last update timestamp | +## Knowledge File Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | ------------------------------------ | --------------------------------- | +| id | Text | PRIMARY KEY | Unique identifier (UUID) | +| user_id | Text | NOT NULL | Owner of the relationship | +| knowledge_id | Text | FOREIGN KEY(knowledge.id), NOT NULL | Reference to the knowledge base | +| file_id | Text | FOREIGN KEY(file.id), NOT NULL | Reference to the file | +| created_at | BigInteger | NOT NULL | Creation timestamp | +| updated_at | BigInteger | NOT NULL | Last update timestamp | + +Things to know about the knowledge_file table: + +- Unique constraint on (`knowledge_id`, `file_id`) to prevent duplicate entries +- Foreign key relationships with CASCADE delete +- Indexed on `knowledge_id`, `file_id`, and `user_id` for performance + The `access_control` fields expected structure: ```python @@ -644,3 +698,57 @@ erDiagram json access_control } ``` + +--- + +## Database Encryption with SQLCipher + +For enhanced security, Open WebUI supports at-rest encryption for its primary SQLite database using SQLCipher. This is recommended for deployments handling sensitive data where using a larger database like PostgreSQL is not needed. + +### Prerequisites + +SQLCipher encryption requires additional dependencies that are **not included by default**. Before using this feature, you must install: + +- The **SQLCipher system library** (e.g., `libsqlcipher-dev` on Debian/Ubuntu, `sqlcipher` on macOS via Homebrew) +- The **`sqlcipher3-wheels`** Python package (`pip install sqlcipher3-wheels`) + +For Docker users, this means building a custom image with these dependencies included. + +### Configuration + +To enable encryption, set the following environment variables: + +```bash +# Required: Set the database type to use SQLCipher +DATABASE_TYPE=sqlite+sqlcipher + +# Required: Set a secure password for database encryption +DATABASE_PASSWORD=your-secure-password +``` + +When these are set and a full `DATABASE_URL` is **not** explicitly defined, Open WebUI will automatically create and use an encrypted database file at `./data/webui.db`. + +### Important Notes + +:::danger + +- The **`DATABASE_PASSWORD`** environment variable is **required** when using `sqlite+sqlcipher`. +- The **`DATABASE_TYPE`** variable tells Open WebUI which connection logic to use. Setting it to `sqlite+sqlcipher` activates the encryption feature. +- **Keep the password secure**, as it is needed to decrypt and access all application data. +- **Losing the password means losing access to all data** in the encrypted database. + +::: + +### Related Database Environment Variables + +| Variable | Default | Description | +|----------|---------|-------------| +| `DATABASE_TYPE` | `None` | Set to `sqlite+sqlcipher` for encrypted SQLite | +| `DATABASE_PASSWORD` | - | Encryption password (required for SQLCipher) | +| `DATABASE_ENABLE_SQLITE_WAL` | `False` | Enable Write-Ahead Logging for better performance | +| `DATABASE_POOL_SIZE` | `None` | Database connection pool size | +| `DATABASE_POOL_TIMEOUT` | `30` | Pool connection timeout in seconds | +| `DATABASE_POOL_RECYCLE` | `3600` | Pool connection recycle time in seconds | + +For more details, see the [Environment Variable Configuration](/getting-started/env-configuration) documentation. + From eeb0dd196c4f9a21fa324de81baaa15740b9e96c Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:21:27 +0100 Subject: [PATCH 22/66] Update improve-performance-local.md --- docs/tutorials/tips/improve-performance-local.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/tutorials/tips/improve-performance-local.md b/docs/tutorials/tips/improve-performance-local.md index dc1c6b047..a0b0280b7 100644 --- a/docs/tutorials/tips/improve-performance-local.md +++ b/docs/tutorials/tips/improve-performance-local.md @@ -93,6 +93,7 @@ Many of these settings can also be configured directly in the **Admin Panel > Se Set a dedicated lightweight model for background tasks: ```bash +# For Ollama models TASK_MODEL=llama3.2:3b # For OpenAI-compatible endpoints From 40c38b5ef65ffb47a9a703e84488a898e30ee3df Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:28:11 +0100 Subject: [PATCH 23/66] fix CI --- src/components/SidebarBanners.tsx | 20 ++++++++++---------- src/components/Sponsors/SidebarBanner.tsx | 4 ++-- src/components/Sponsors/TopBanner.tsx | 4 ++-- src/components/TopBanners.tsx | 20 ++++++++++---------- src/theme/Navbar/Content/index.tsx | 2 +- 5 files changed, 25 insertions(+), 25 deletions(-) diff --git a/src/components/SidebarBanners.tsx b/src/components/SidebarBanners.tsx index d3f44d250..0924f323e 100644 --- a/src/components/SidebarBanners.tsx +++ b/src/components/SidebarBanners.tsx @@ -4,19 +4,19 @@ import { useEffect, useState } from "react"; export const SidebarBanners = () => { const items = [ { - imgSrc: '/sponsors/banners/openwebui-banner.png', - mobileImgSrc: '/sponsors/banners/openwebui-banner-mobile.png', - url: 'https://docs.openwebui.com/enterprise', - name: 'Open WebUI Inc.', + imgSrc: "/sponsors/banners/openwebui-banner.png", + mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", + url: "https://docs.openwebui.com/enterprise", + name: "Open WebUI Inc.", description: - 'Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.' + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support." }, { - imgSrc: '/sponsors/banners/openwebui-banner.png', - mobileImgSrc: '/sponsors/banners/openwebui-banner-mobile.png', - url: 'https://careers.openwebui.com', - name: 'Open WebUI Inc.', - description: '**We are hiring!** Shape the way humanity engages with _intelligence_.' + imgSrc: "/sponsors/banners/openwebui-banner.png", + mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", + url: "https://careers.openwebui.com", + name: "Open WebUI Inc.", + description: "**We are hiring!** Shape the way humanity engages with _intelligence_." }, ]; diff --git a/src/components/Sponsors/SidebarBanner.tsx b/src/components/Sponsors/SidebarBanner.tsx index 09a1d3840..8b2cd0b71 100644 --- a/src/components/Sponsors/SidebarBanner.tsx +++ b/src/components/Sponsors/SidebarBanner.tsx @@ -1,4 +1,4 @@ -import {marked} from 'marked'; +import { marked } from "marked"; export const SidebarBanner = ({ item }) => { return ( @@ -18,7 +18,7 @@ export const SidebarBanner = ({ item }) => {
-
+
diff --git a/src/components/Sponsors/TopBanner.tsx b/src/components/Sponsors/TopBanner.tsx index ca17a4f0b..de9cdeb27 100644 --- a/src/components/Sponsors/TopBanner.tsx +++ b/src/components/Sponsors/TopBanner.tsx @@ -1,4 +1,4 @@ -import {marked} from 'marked'; +import { marked } from "marked"; export const TopBanner = ({ item, @@ -51,7 +51,7 @@ export const TopBanner = ({ {description && (
-
+
)}
diff --git a/src/components/TopBanners.tsx b/src/components/TopBanners.tsx index db9ae3da1..1e37e4321 100644 --- a/src/components/TopBanners.tsx +++ b/src/components/TopBanners.tsx @@ -9,19 +9,19 @@ export const TopBanners = ({ }) => { const items = [ { - imgSrc: '/sponsors/banners/openwebui-banner.png', - mobileImgSrc: '/sponsors/banners/openwebui-banner-mobile.png', - url: 'https://docs.openwebui.com/enterprise', - name: 'Open WebUI Inc.', + imgSrc: "/sponsors/banners/openwebui-banner.png", + mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", + url: "https://docs.openwebui.com/enterprise", + name: "Open WebUI Inc.", description: - 'Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.' + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support." }, { - imgSrc: '/sponsors/banners/openwebui-banner.png', - mobileImgSrc: '/sponsors/banners/openwebui-banner-mobile.png', - url: 'https://careers.openwebui.com', - name: 'Open WebUI Inc.', - description: '**We are hiring!** Shape the way humanity engages with _intelligence_.' + imgSrc: "/sponsors/banners/openwebui-banner.png", + mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", + url: "https://careers.openwebui.com", + name: "Open WebUI Inc.", + description: "**We are hiring!** Shape the way humanity engages with _intelligence_." }, ]; diff --git a/src/theme/Navbar/Content/index.tsx b/src/theme/Navbar/Content/index.tsx index e7072c83e..4b1d124f1 100644 --- a/src/theme/Navbar/Content/index.tsx +++ b/src/theme/Navbar/Content/index.tsx @@ -16,7 +16,7 @@ export default function ContentWrapper(props: Props): JSX.Element {
- +
From 81ba1f2ec030c7c3faef663ba55378f9c525ca5e Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:32:06 +0100 Subject: [PATCH 24/66] fix CI --- src/components/SidebarBanners.tsx | 4 +- src/components/SponsorList.tsx | 58 +++++++++++++-------------- src/components/Sponsors/TopBanner.tsx | 2 +- src/components/TopBanners.tsx | 4 +- src/theme/Navbar/Content/index.tsx | 2 +- 5 files changed, 35 insertions(+), 35 deletions(-) diff --git a/src/components/SidebarBanners.tsx b/src/components/SidebarBanners.tsx index 0924f323e..3cade9983 100644 --- a/src/components/SidebarBanners.tsx +++ b/src/components/SidebarBanners.tsx @@ -9,14 +9,14 @@ export const SidebarBanners = () => { url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", description: - "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support." + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://careers.openwebui.com", name: "Open WebUI Inc.", - description: "**We are hiring!** Shape the way humanity engages with _intelligence_." + description: "**We are hiring!** Shape the way humanity engages with _intelligence_.", }, ]; diff --git a/src/components/SponsorList.tsx b/src/components/SponsorList.tsx index eaa45c2a3..7e8b25a83 100644 --- a/src/components/SponsorList.tsx +++ b/src/components/SponsorList.tsx @@ -1,27 +1,27 @@ import { Sponsor } from "@site/src/components/Sponsors/Sponsor"; export const SponsorList = () => { - const emeraldSponsors = [ - // { - // imgSrc: "/sponsors/logos/n8n.png", - // url: "https://n8n.io/", - // name: "n8n", - // description: "Does your interface have a backend yet? Try n8n", - // }, - - // { - // imgSrc: "/sponsors/logos/warp.png", - // url: "https://warp.dev/open-webui", - // name: "Warp", - // description: "The intelligent terminal for developers", - // }, - // { - // imgSrc: "/sponsors/logos/tailscale.png", - // url: "https://tailscale.com/blog/self-host-a-local-ai-stack/?utm_source=OpenWebUI&utm_medium=paid-ad-placement&utm_campaign=OpenWebUI-Docs", - // name: "Tailscale", - // description: "Connect self-hosted AI to any device with Tailscale", - // }, - ]; + // const emeraldSponsors = [ + // { + // imgSrc: "/sponsors/logos/n8n.png", + // url: "https://n8n.io/", + // name: "n8n", + // description: "Does your interface have a backend yet? Try n8n", + // }, + + // { + // imgSrc: "/sponsors/logos/warp.png", + // url: "https://warp.dev/open-webui", + // name: "Warp", + // description: "The intelligent terminal for developers", + // }, + // { + // imgSrc: "/sponsors/logos/tailscale.png", + // url: "https://tailscale.com/blog/self-host-a-local-ai-stack/?utm_source=OpenWebUI&utm_medium=paid-ad-placement&utm_campaign=OpenWebUI-Docs", + // name: "Tailscale", + // description: "Connect self-hosted AI to any device with Tailscale", + // }, + // ]; const sponsors = [ { @@ -35,8 +35,8 @@ export const SponsorList = () => { return (
{/*
-
Diamond
-
+
Diamond
+
@@ -44,8 +44,8 @@ export const SponsorList = () => {
-
Sapphire
-
+
Sapphire
+
@@ -53,8 +53,8 @@ export const SponsorList = () => {
-
Topaz
-
+
Topaz
+
@@ -68,9 +68,9 @@ export const SponsorList = () => {
- {emeraldSponsors.map((sponsor, sponsorIdx) => ( + {/* {emeraldSponsors.map((sponsor, sponsorIdx) => ( - ))} + ))} */}
diff --git a/src/components/Sponsors/TopBanner.tsx b/src/components/Sponsors/TopBanner.tsx index de9cdeb27..b7cfa1733 100644 --- a/src/components/Sponsors/TopBanner.tsx +++ b/src/components/Sponsors/TopBanner.tsx @@ -2,7 +2,7 @@ import { marked } from "marked"; export const TopBanner = ({ item, - bannerClassName = "h-18 ", + bannerClassName = "h-18", label = true, description = true, mobile = true, diff --git a/src/components/TopBanners.tsx b/src/components/TopBanners.tsx index 1e37e4321..6d136d04e 100644 --- a/src/components/TopBanners.tsx +++ b/src/components/TopBanners.tsx @@ -14,14 +14,14 @@ export const TopBanners = ({ url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", description: - "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support." + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://careers.openwebui.com", name: "Open WebUI Inc.", - description: "**We are hiring!** Shape the way humanity engages with _intelligence_." + description: "**We are hiring!** Shape the way humanity engages with _intelligence_.", }, ]; diff --git a/src/theme/Navbar/Content/index.tsx b/src/theme/Navbar/Content/index.tsx index 4b1d124f1..6b1bc2032 100644 --- a/src/theme/Navbar/Content/index.tsx +++ b/src/theme/Navbar/Content/index.tsx @@ -9,7 +9,7 @@ type Props = WrapperProps; export default function ContentWrapper(props: Props): JSX.Element { return ( <> -
+
From 6fa73c67402fa8b160530afa29d1b9820702294c Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:35:10 +0100 Subject: [PATCH 25/66] fix ci --- src/components/SidebarBanners.tsx | 3 +-- src/components/TopBanners.tsx | 3 +-- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/components/SidebarBanners.tsx b/src/components/SidebarBanners.tsx index 3cade9983..9d480151a 100644 --- a/src/components/SidebarBanners.tsx +++ b/src/components/SidebarBanners.tsx @@ -8,8 +8,7 @@ export const SidebarBanners = () => { mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", - description: - "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", + description: "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", diff --git a/src/components/TopBanners.tsx b/src/components/TopBanners.tsx index 6d136d04e..0dabb3d02 100644 --- a/src/components/TopBanners.tsx +++ b/src/components/TopBanners.tsx @@ -13,8 +13,7 @@ export const TopBanners = ({ mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", - description: - "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", + description: "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", From 051a5b156171e9297870fa6655d53c60ef9e9ed6 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:42:37 +0100 Subject: [PATCH 26/66] fix ci --- .gitattributes | 1 + .gitignore | 4 ++++ src/components/SidebarBanners.tsx | 6 ++++-- src/components/Sponsors/TopBanner.tsx | 4 +++- src/components/TopBanners.tsx | 6 ++++-- 5 files changed, 16 insertions(+), 5 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..6313b56c5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +* text=auto eol=lf diff --git a/.gitignore b/.gitignore index b2d6de306..280c6e6ea 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,7 @@ npm-debug.log* yarn-debug.log* yarn-error.log* + +# Local Node environment +.local_node +node.zip diff --git a/src/components/SidebarBanners.tsx b/src/components/SidebarBanners.tsx index 9d480151a..4593af238 100644 --- a/src/components/SidebarBanners.tsx +++ b/src/components/SidebarBanners.tsx @@ -8,14 +8,16 @@ export const SidebarBanners = () => { mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", - description: "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", + description: + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://careers.openwebui.com", name: "Open WebUI Inc.", - description: "**We are hiring!** Shape the way humanity engages with _intelligence_.", + description: + "**We are hiring!** Shape the way humanity engages with _intelligence_.", }, ]; diff --git a/src/components/Sponsors/TopBanner.tsx b/src/components/Sponsors/TopBanner.tsx index b7cfa1733..e05ccaa5a 100644 --- a/src/components/Sponsors/TopBanner.tsx +++ b/src/components/Sponsors/TopBanner.tsx @@ -51,7 +51,9 @@ export const TopBanner = ({ {description && (
-
+
)}
diff --git a/src/components/TopBanners.tsx b/src/components/TopBanners.tsx index 0dabb3d02..b3e6c76eb 100644 --- a/src/components/TopBanners.tsx +++ b/src/components/TopBanners.tsx @@ -13,14 +13,16 @@ export const TopBanners = ({ mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://docs.openwebui.com/enterprise", name: "Open WebUI Inc.", - description: "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", + description: + "Upgrade to a licensed plan for enhanced capabilities, including custom theming and branding, and dedicated support.", }, { imgSrc: "/sponsors/banners/openwebui-banner.png", mobileImgSrc: "/sponsors/banners/openwebui-banner-mobile.png", url: "https://careers.openwebui.com", name: "Open WebUI Inc.", - description: "**We are hiring!** Shape the way humanity engages with _intelligence_.", + description: + "**We are hiring!** Shape the way humanity engages with _intelligence_.", }, ]; From e025953d1f3b2e98d332a1caf6ddccdafe93eb15 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:48:09 +0100 Subject: [PATCH 27/66] rem warn ci --- docusaurus.config.ts | 1 - 1 file changed, 1 deletion(-) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index aaec96d14..b3f9ab0b6 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -20,7 +20,6 @@ const config: Config = { projectName: "docs", // Usually your repo name. onBrokenLinks: "throw", - onBrokenMarkdownLinks: "warn", // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you From 77e171cf3e0be1034e14af364bc1f8ed7ae49039 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 18:55:10 +0100 Subject: [PATCH 28/66] watchtower --- .../quick-start/tab-docker/DockerUpdating.md | 10 +++++++--- docs/intro.mdx | 6 +++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md index e66ea749f..f5aacce8c 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md +++ b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md @@ -2,12 +2,16 @@ To update your local Docker installation to the latest version, you can either use **Watchtower** or manually update the container. -### Option 1: Using Watchtower +### Option 1: Using Watchtower (Recommended Fork) -With [Watchtower](https://containrrr.dev/watchtower/), you can automate the update process: +:::info Deprecation Notice +The original `containrrr/watchtower` is **no longer maintained** and may fail with newer Docker versions. We recommend using the `nickfedor/watchtower` fork. +::: + +With [Watchtower](https://github.com/nickfedor/watchtower), you can automate the update process: ```bash -docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui +docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once open-webui ``` *(Replace `open-webui` with your container's name if it's different.)* diff --git a/docs/intro.mdx b/docs/intro.mdx index 7b4fd700c..b99e8a023 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -130,15 +130,15 @@ docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --r To update Open WebUI container easily, follow these steps: #### Manual Update -Use [Watchtower](https://containrrr.dev/watchtower) to update your Docker container manually: +Use [Watchtower](https://github.com/nickfedor/watchtower) to update your Docker container manually: ```bash -docker run --rm -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui +docker run --rm -v /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --run-once open-webui ``` #### Automatic Updates Keep your container updated automatically every 5 minutes: ```bash -docker run -d --name watchtower --restart unless-stopped -v /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --interval 300 open-webui +docker run -d --name watchtower --restart unless-stopped -v /var/run/docker.sock:/var/run/docker.sock nickfedor/watchtower --interval 300 open-webui ``` 🔧 **Note**: Replace `open-webui` with your container name if it's different. From d6e5961cf59b82b41da24bcc36fd07c8ec551195 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 19:02:31 +0100 Subject: [PATCH 29/66] dev --- .../advanced-topics/development.md | 29 +++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index 158e3b5ed..13e342e31 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -140,6 +140,26 @@ VS Code's integrated terminal feature makes managing multiple terminals incredib *(Using Conda is optional but strongly recommended for managing Python dependencies and avoiding conflicts.)* If you choose not to use Conda, ensure you are using Python 3.11 or higher and proceed to the next step, but be aware of potential dependency conflicts. +2. **Alternative: Create and Activate a Python venv:** + + If you prefer using Python's built-in `venv` module instead of Conda, follow these steps: + + - **Create the virtual environment:** + ```bash + python3 -m venv venv + ``` + - **Activate the virtual environment:** + - **Linux/macOS:** + ```bash + source venv/bin/activate + ``` + - **Windows:** + ```powershell + .\venv\Scripts\activate + ``` + + Once activated, your terminal prompt should show `(venv)`. You can now proceed to install dependencies. + 1. **Install Backend Dependencies:** - In your *backend* terminal (and with the Conda environment activated if you are using Conda), run: @@ -263,6 +283,15 @@ Hot reload (or hot module replacement - HMR) is a fantastic development feature 6. **IDE/Editor Issues:** In rare cases, issues with your IDE or code editor might prevent file changes from being properly detected by the development servers. Try restarting your IDE or ensuring that files are being saved correctly. 7. **Configuration Problems (Advanced):** If none of the above steps work, there might be a more complex configuration issue with the frontend or backend development server setup. Consult the project's documentation, configuration files (e.g., `vite.config.js` for frontend, backend server configuration files), or seek help from the Open WebUI community or maintainers. +### 🖼️ Icons Not Loading? (CORS Issues) + +If you find that **icons or other static assets are failing to load**, it is often due to **Cross-Origin Resource Sharing (CORS)** restrictions. This happens when the frontend (running on one port, e.g., `5173`) tries to request resources from the backend (running on another port, e.g., `8080`) without explicit permission. + +**Solution:** +You need to configure the `CORS_ALLOW_ORIGIN` environment variable in your backend. +- Check the [Environment Configuration](../getting-started/env-configuration.mdx#cors-settings) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`). +- In a development environment, you can often set this in your `backend/dev.sh` script or your `.env` file. + ## Contributing to Open WebUI We warmly welcome your contributions to Open WebUI! Your help is valuable in making this project even better. Here's a quick guide for a smooth and effective contribution workflow: From 64e347c1ab639f33a7f4fd1a817c71e067cc8d5b Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:14:25 +0100 Subject: [PATCH 30/66] update RBAC --- docs/features/rbac/groups.md | 100 ++++++++-------- docs/features/rbac/permissions.md | 185 ++++++++++++++++++++---------- docs/features/rbac/roles.md | 92 +++++++-------- 3 files changed, 226 insertions(+), 151 deletions(-) diff --git a/docs/features/rbac/groups.md b/docs/features/rbac/groups.md index ffbbcc2c4..09e3ee1e7 100644 --- a/docs/features/rbac/groups.md +++ b/docs/features/rbac/groups.md @@ -3,75 +3,85 @@ sidebar_position: 3 title: "Groups" --- -Groups allow administrators to -- assign permissions to multiple users at once, simplifying access management -- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to specific groups -- Specify access to a resource for a group to either "read" or "write" (write access implies read) - -:::info - -Note that the permissions model is permissive. If a user is a member of two groups that define different permissions for a resource, the most permissive permission is applied. +Groups in Open WebUI are a powerful mechanism for organizing users and managing access control at scale. They serve two primary purposes: +1. **Permission Management:** Assigning granular permissions to multiple users efficiently. +2. **Resource Access Control:** controlling who can access specific private resources (Models, Knowledge Bases, Tools). +:::info Permission Merging Logic +Open WebUI permissions are **additive** (Union-based). +* If a user is in multiple groups, they receive the **superset** of all permissions. +* If *Group A* allows "Image Generation" and *Group B* does not, a user in both groups **WILL** have access to Image Generation. +* "Deny" permissions do not exist; you can only "Grant" permissions. ::: -### Group Structure - -Each group in Open WebUI contains: +## Group Management -- A unique identifier -- Name and description -- Owner/creator reference -- List of member user IDs -- Permission configuration -- Additional metadata +Groups can be managed in the **Admin Panel > Groups** section. -### Group Management +### Group Configuration +When creating or editing a group, you can configure its visibility in the system: -Groups can be: +* **Allow Group Sharing**: (Default: **On**) + * **Enabled**: The group will appear in the "Access Control" dropdowns when users share Chat items, Models, or Knowledge lists. Use this for teams or project groups that need to collaborate on content. + * **Disabled**: The group is **hidden** from sharing menus. This is designed for groups used solely for **RBAC Permission assignment** (e.g., granting "Image Generation" rights). Hiding these prevents the Sharing UI from becoming cluttered with technical/administrative groups. -- **Created manually** by administrators through the user interface -- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled -- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` - are enabled +:::tip Strategy: Permission Groups vs. Sharing Groups +To maintain a clean and manageable system, consider separating your groups into two distinct categories using a naming scheme: -### OAuth Group Integration +1. **Permission Groups** (e.g., prefix `[Perms]`, `Role-`, or `P-`) + * **Purpose**: Exclusively for granting features (e.g., `[Perms] Image Gen`, `[Perms] Web Search`). + * **Config**: Disable **Allow Group Sharing**. + * **Result**: Users get the features they need, but these technical groups don't clutter the "Share" menu. -When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims: +2. **Sharing Groups** (e.g., prefix `Team-`, `Project-`, or normal names) + * **Purpose**: Exclusively for organizing people (e.g., `Marketing`, `Engineering`, `Team Alpha`) to share resources. + * **Config**: Enable **Allow Group Sharing**. + * **Best Practice**: **Disable all permissions** in these groups. + * Rely on *Global Default Permissions* (or separate *Permission Groups*) for feature rights. + * *Why?* This ensures painless **Permission Revocation**. If you decide to disable a feature (e.g., "Web Search") globally, it will instantly take effect for everyone. If your Sharing Groups had "Web Search" enabled, you would have to manually update every single group to remove the right, as the Group's `True` status would override the Global `False`. Keep functional groups clean to maintain Global control. +::: -- Users are added to Open WebUI groups that match their OAuth claims -- Users are removed from groups not present in their OAuth claims -- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically - created +### Creation Methods +* **Manual Creation:** Administrators can manually create groups and add users via the UI. +* **OAuth Synchronization:** If `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled, groups can be synced from your OAuth provider (e.g., Keycloak, Azure AD). + * **Auto-Creation:** With `ENABLE_OAUTH_GROUP_CREATION`, groups that don't exist locally will be created automatically. + * **Membership Sync:** Users are strictly added/removed from groups to match their OAuth claims. -## Group Permissions +### Group Structure +A group definition typically includes: +* **Name**: The display name of the group. +* **Description**: Purpose of the group. +* **Permissions**: A detailed JSON object overriding default user permissions (see [Permissions](./permissions.md)). +* **Members**: A list of User IDs belonging to the group. -Groups can be used to make sets of permissions available to users. For example, a group could be created for "Data -Scientists" that has read and write access to all models, knowledge bases, and tools. +## Assigning Permissions to Groups -## Resource Access Control for Groups +When editing a group, you can toggle specific permissions. +* **Default State**: By default, a group grants *no* extra permissions; members rely on the global defaults. +* **Granting Access**: Toggling a permission (e.g., "Web Search") to **ON** for a group means all members get that feature, even if it's disabled globally. -Open WebUI implements granular access control for resources like models, knowledge bases, prompts, and tools. Access can -be controlled at both the user and group level. +## Resource Access (RBAC) -To enable access control for a resource, set its access to "private" and then open access to specific groups. +You can restrict access to specific objects (like a proprietary Model or sensitive Knowledge Base) using Groups. -### Access Control Structure +1. **Tag the Resource**: When creating/editing a Model or Knowledge Base, set its visibility to **Private** or **Restricted**. +2. **Grant Access**: Select the specific **Groups** (or individual users) that should have "Read" or "Write" access. -Resources like knowledge bases use an access control structure that specifies read and write permissions for both users -and groups: +### Access Control Object +At a deeper level, resources store an access control list (ACL) looking like this: ```json { "read": { - "group_ids": ["group_id1", "group_id2"], - "user_ids": ["user_id1", "user_id2"] + "group_ids": ["marketing-team-id", "admins-id"], + "user_ids": [] }, "write": { - "group_ids": ["group_id1", "group_id2"], - "user_ids": ["user_id1", "user_id2"] + "group_ids": ["admins-id"], + "user_ids": ["editor-user-id"] } } ``` - -This structure allows for precise control over who can view and modify specific resources. +* **Read**: Users can view and use the resource. +* **Write**: Users can update or delete the resource. diff --git a/docs/features/rbac/permissions.md b/docs/features/rbac/permissions.md index b82cc6fd7..bc38f92e2 100644 --- a/docs/features/rbac/permissions.md +++ b/docs/features/rbac/permissions.md @@ -3,72 +3,135 @@ sidebar_position: 3 title: "Permissions" --- -The `Permissions` section of the `Workspace` within Open WebUI allows administrators to configure access controls and feature availability for users. This powerful system enables fine-grained control over what users can access and modify within the application. - -Administrators can manage permissions in the following ways: - -1. **User Interface:** The Workspace's Permissions section provides a graphical interface for configuring permissions. -2. **Environment Variables:** Permissions can be set using environment variables, which are stored as `PersistentConfig` variables. -3. **Group Management:** Assigning users to groups with predefined permissions. - -## Workspace Permissions - -Workspace permissions control access to core components of the Open WebUI platform: - -- **Models Access**: Toggle to allow users to access and manage custom models. (Environment variable: `USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS`) -- **Knowledge Access**: Toggle to allow users to access and manage knowledge bases. (Environment variable: `USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS`) -- **Prompts Access**: Toggle to allow users to access and manage saved prompts. (Environment variable: `USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS`) -- **Tools Access**: Toggle to allow users to access and manage tools. (Environment variable: `USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS`) *Note: Enabling this gives users the ability to upload arbitrary code to the server.* - -## Chat Permissions - -Chat permissions determine what actions users can perform within chat conversations: - -- **Allow Chat Controls**: Toggle to enable access to chat control options. -- **Allow File Upload**: Toggle to permit users to upload files during chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_FILE_UPLOAD`) -- **Allow Chat Delete**: Toggle to permit users to delete chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_DELETE`) -- **Allow Chat Edit**: Toggle to permit users to edit messages in chat conversations. (Environment variable: `USER_PERMISSIONS_CHAT_EDIT`) -- **Allow Temporary Chat**: Toggle to permit users to create temporary chat sessions. (Environment variable: `USER_PERMISSIONS_CHAT_TEMPORARY`) - -## Features Permissions -Features permissions control access to specialized capabilities within Open WebUI: - -- **Web Search**: Toggle to allow users to perform web searches during chat sessions. (Environment variable: `ENABLE_WEB_SEARCH`) -- **Image Generation**: Toggle to allow users to generate images. (Environment variable: `ENABLE_IMAGE_GENERATION`) -- **Code Interpreter**: Toggle to allow users to use the code interpreter feature. (Environment variable: `USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) -- **Direct Tool Servers**: Toggle to allow users to connect directly to tool servers. (Environment variable: `USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS`) - -## Default Permission Settings - -By default, Open WebUI applies the following permission settings: - -**Workspace Permissions**: - -- Models Access: Disabled (`USER_PERMISSIONS_WORKSPACE_MODELS_ACCESS=False`) -- Knowledge Access: Disabled (`USER_PERMISSIONS_WORKSPACE_KNOWLEDGE_ACCESS=False`) -- Prompts Access: Disabled (`USER_PERMISSIONS_WORKSPACE_PROMPTS_ACCESS=False`) -- Tools Access: Disabled (`USER_PERMISSIONS_WORKSPACE_TOOLS_ACCESS=False`) - -**Chat Permissions**: +The `Permissions` section of the `Workspace` within Open WebUI allows administrators to configure access controls and feature availability for users. This powerful system enables fine-grained control over what users can access and modify within the application. -- Allow Chat Controls: Enabled -- Allow File Upload: Enabled (`USER_PERMISSIONS_CHAT_FILE_UPLOAD=True`) -- Allow Chat Delete: Enabled (`USER_PERMISSIONS_CHAT_DELETE=True`) -- Allow Chat Edit: Enabled (`USER_PERMISSIONS_CHAT_EDIT=True`) -- Allow Temporary Chat: Enabled (`USER_PERMISSIONS_CHAT_TEMPORARY=True`) +Administrators can manage permissions in three primary ways: +1. **Global Default Permissions:** Set the baseline permissions for all user accounts via the Admin Panel. +2. **Group Permissions:** Create groups with specific permission overrides (e.g., a "Power Users" group with access to image generation). +3. **Role-Based Access:** The `Pending` role has no access, `Admin` has full access, and `User` is subject to the permission system. + +:::info Permission Logic +Permissions in Open WebUI are **additive**. +* A user's effective permissions are the combination of **Global Defaults** and all their **Group Memberships**. +* **True takes precedence over False**: If *any* source (Global Default or *any* single Group) grants a permission, the user **will** have that permission. +* **No "Deny" ability**: You cannot use a specific group to "take away" a permission that is granted by another group or by the global defaults. To restrict a feature, it must be disabled in the Global Defaults *and* disabled in **all** groups the user belongs to. +::: + +:::tip Best Practice: Principle of Least Privilege +Since permissions are **additive**, the recommended security strategy is to start with **Restriction**: +1. **minimize Global Default Permissions**: Configure the default permissions (Admin > Settings > Users) to include *only* what absolutely every user should have. +2. **Grant via Groups**: Create specific groups (e.g., "Creators", "Power Users") to explicitly **grant** advanced features like Image Generation or File Uploads. + +This approach ensures that new users don't accidentally get access to sensitive features, while allowing you to easily promote users by simply adding them to the relevant group. +::: + +## Permission Categories + +Permissions are organized into four main categories: **Workspace**, **Sharing**, **Chat**, and **Features**. + +### 1. Workspace Permissions +Controls access to the "Workspace" section where users create and manage resources. +Some permissions are **dependent** on others (e.g., you cannot import models if you cannot access the Models workspace). + +| Permission | Description | +| :--- | :--- | +| **Models Access** | **(Parent)** Access the **Models** workspace to create or edit custom models. | +| **Models Import** | *(Requires Models Access)* Ability to import models from JSON/files. | +| **Models Export** | *(Requires Models Access)* Ability to export models to files. | +| **Knowledge Access** | Access the **Knowledge** workspace to manage knowledge bases. | +| **Prompts Access** | **(Parent)** Access the **Prompts** workspace to manage custom system prompts. | +| **Prompts Import** | *(Requires Prompts Access)* Ability to import prompts. | +| **Prompts Export** | *(Requires Prompts Access)* Ability to export prompts. | +| **Tools Access** | **(Parent)** Access the **Tools** workspace to manage functions/tools. | +| **Tools Import** | *(Requires Tools Access)* Ability to import tools. | +| **Tools Export** | *(Requires Tools Access)* Ability to export tools. | + +### 2. Sharing Permissions +Controls what users can share with the community or make public. + +| Permission | Description | +| :--- | :--- | +| **Share Models** | **(Parent)** Ability to share models (make them accessible to others). | +| **Public Models** | *(Requires Share Models)* Ability to make models publicly discoverable. | +| **Share Knowledge** | **(Parent)** Ability to share knowledge bases. | +| **Public Knowledge** | *(Requires Share Knowledge)* Ability to make knowledge bases public. | +| **Share Prompts** | **(Parent)** Ability to share prompts. | +| **Public Prompts** | *(Requires Share Prompts)* Ability to make prompts public. | +| **Share Tools** | **(Parent)** Ability to share tools. | +| **Public Tools** | *(Requires Share Tools)* Ability to make tools public. | +| **Share Notes** | **(Parent)** Ability to share Notes. | +| **Public Notes** | *(Requires Share Notes)* Ability to make Notes public. | + +### 3. Chat Permissions +Controls the features available to the user inside the chat interface. + +| Permission | Description | +| :--- | :--- | +| **Chat Controls** | **(Parent)** Access to advanced chat settings. Required for Valves, System Prompt, and Parameters. | +| **Model Valves** | *(Requires Chat Controls)* Access to model-specific configuration "valves". | +| **System Prompt** | *(Requires Chat Controls)* Ability to edit the system prompt for a conversation. | +| **Parameters** | *(Requires Chat Controls)* Ability to adjust LLM parameters (e.g., temperature, top_k). | +| **File Upload** | Ability to upload files to the chat. | +| **Delete Chat** | Ability to delete entire chat conversations. | +| **Delete Message** | Ability to delete individual messages. | +| **Edit Message** | Ability to edit messages. | +| **Continue Response** | Ability to use the "Continue" feature for truncated responses. | +| **Regenerate Response**| Ability to regenerate an AI response. | +| **Rate Response** | Ability to thumbs up/down responses. | +| **Share Chat** | Ability to generate a share link for a chat. | +| **Export Chat** | Ability to export chat history. | +| **Speech-to-Text (STT)**| Ability to use voice input. | +| **Text-to-Speech (TTS)**| Ability to use voice output. | +| **Audio Call** | Ability to use the real-time audio call feature. | +| **Multiple Models** | Ability to select multiple models for a simultaneous response. | +| **Temporary Chat** | **(Parent)** Ability to toggle "Temporary Chat" (incognito mode/history off). | +| **Enforced Temporary** | *(Requires Temporary Chat)* **Restricts** the user to *always* use temporary chat (history disabled). | + +### 4. Features Permissions +Controls access to broad platform capabilities. + +| Permission | Description | +| :--- | :--- | +| **API Keys** | Ability to generate Personal Access Tokens (API Keys) in User Settings. | +| **Notes** | Access to the "Notes" feature. | +| **Channels** | Access to the "Channels" feature. | +| **Folders** | Ability to use folders for organizing chats. | +| **Web Search** | Ability to use Web Search integration. | +| **Image Generation** | Ability to use Image Generation tools. | +| **Code Interpreter** | Ability to use the Python Code Interpreter. | +| **Direct Tool Servers** | Ability to connect to custom Tool Servers in settings. | + +:::warning API Keys Security & Admin Access +The **API Keys** permission (`features.api_keys`) is treated with higher security and works differently than other features: + +1. **Global Toggle Required**: + The feature must be enabled globally in **Admin Settings > General > Enable API Keys**. If this is off, *no one* (not even groups with permission) can generate keys. + +2. **Permission Check Required**: + In addition to the global toggle, the user must look for the permission `features.api_keys`. + +3. **Admins Are Not Exempt**: + Unlike most other permissions which Admins bypass, **Administrators require this permission** to generate API keys. They are subject to the same checks as regular users for this critical security feature. + +**Recommended "Least Privilege" Configuration**: +* **Step 1**: Disable `API Keys` in **Global Default Permissions** (so new users don't get it by default). +* **Step 2**: Create a specific Group (e.g., `🔐 API Users`) with `API Keys` enabled. +* **Step 3**: Manually add specific users—including yourself/Admins—to this group to grant access. +::: -**Features Permissions**: +## Managing Permissions -- Web Search: Enabled (`ENABLE_WEB_SEARCH=True`) -- Image Generation: Enabled (`ENABLE_IMAGE_GENERATION=True`) -- Code Interpreter: Enabled (`USER_PERMISSIONS_FEATURES_CODE_INTERPRETER`) -- Direct Tool Servers: Disabled (`USER_PERMISSIONS_FEATURES_DIRECT_TOOL_SERVERS=False`) +Administrators can adjust these permissions through the **Admin Panel > Settings > Users > Permissions**. -Administrators can change the default permissions in the user interface under "users" in the admin panel. +* **Default Permissions**: Changing settings here applies to all users immediately, unless they are granted the permission via a Group. +* **Group Permissions**: Go to **Admin Panel > Groups**, verify a group, and edit its permissions. Group permissions override the default (e.g., if "Image Generation" is disabled by default, a "Creative User" group can have it enabled). -## Managing Permissions +### Environment Variables -Administrators can adjust these permissions through the user interface or by setting the corresponding environment variables in the configuration. All permission-related environment variables are marked as `PersistentConfig` variables, meaning they are stored internally after the first launch and can be managed through the Open WebUI interface. +While the UI is the recommended way to manage permissions, initial defaults can be set via environment variables. These are typically prefixed with `USER_PERMISSIONS_`. +* `ENABLE_IMAGE_GENERATION=True` +* `ENABLE_WEB_SEARCH=True` +* `USER_PERMISSIONS_CHAT_FILE_UPLOAD=True` -This flexibility allows organizations to implement security policies while still providing users with the tools they need. For more detailed information about environment variables related to permissions, see the [Environment Variable Configuration](https://docs.openwebui.com/getting-started/env-configuration#workspace-permissions) documentation. +See the [Environment Configuration](../getting-started/env-configuration.mdx) guide for a complete list of valid variables. diff --git a/docs/features/rbac/roles.md b/docs/features/rbac/roles.md index 25b2e29ad..bc6817196 100644 --- a/docs/features/rbac/roles.md +++ b/docs/features/rbac/roles.md @@ -3,63 +3,65 @@ sidebar_position: 3 title: "Roles" --- -Open WebUI implements a structured role-based access control system with three primary user roles: -| **Role** | **Description** | **Default Creation** | -|---------------|---------------------------------------------------|----------------------------------| -| Administrator | System administrator with full control | First user account | -| Regular User | Standard user with limited permissions | Subsequent approved users | -| Pending | Unapproved user awaiting administrator activation | New registrations (configurable) | +Open WebUI defines three primary **System Roles** that determine the fundamental access level of a user account. These roles are distinct from [Groups](./groups.md) and [Permissions](./permissions.md). -### Role Assignment +| Role | Keyword | Description | +| :--- | :--- | :--- | +| **Admin** | `admin` | **Superuser**. Full control over the system. | +| **User** | `user` | **Standard User**. Subject to RBAC permissions. | +| **Pending** | `pending` | **Restricted**. No access until approved. | -- **First User:** The first account created on a new Open WebUI instance automatically receives Administrator - privileges. -- **Subsequent Users:** New user registrations are assigned a default role based on the `DEFAULT_USER_ROLE` - configuration. +## Role Details -The default role for new registrations can be configured using the `DEFAULT_USER_ROLE` environment variable: +### Administrator (`admin`) +The Admin role is designed for system maintainers. +* **Full Access**: default access to all resources and settings. +* **Management**: Can manage users, groups, and global configurations. +* **Bypass**: Bypasses most permission checks by default. -```.dotenv -DEFAULT_USER_ROLE=pending # Options: pending, user, admin -``` - -When set to "pending", new users must be manually approved by an administrator before gaining access to the system. - -## User Groups +:::warning Admin Limitations & Best Practices +While Administrators generally have unrestricted access, certain system configurations can limit their capabilities for security and privacy: +* **Privacy Controls**: Environment variables like `ENABLE_ADMIN_CHAT_ACCESS=False` can prevent Admins from viewing user chats. +* **Strict Feature Checks**: Critical security features like **API Keys** (`features.api_keys`) require explicit permission, even for Admins. +* **Access Control Exceptions**: If `BYPASS_ADMIN_ACCESS_CONTROL` is disabled, Admins may require explicit permissions to access private model/knowledge resources. -Groups allow administrators to +For a robust security posture, we recommend including Admins in your permission schema (via Groups) rather than relying solely on the role's implicit bypasses. This ensures consistent access if bypass limitations are ever enabled. +::: -- assign permissions to multiple users at once, simplifying access management -- limit access to specific resources (Models, Tools, etc) by setting their access to "private" then opening access to -specific groups -- Group access to a resource can be set as "read" or "write" +### Standard User (`user`) +This is the default functional role for team members. +* **Subject to Permissions**: Does not have implicit access. All capabilities must be granted via **Global Default Permissions** or **Group Memberships**. +* **Additive Rights**: As explained in the [Permissions](./permissions.md) section, their effective rights are the sum of all their grants. -### Group Structure +### Pending User (`pending`) +The default state for new sign-ups (if configured) or deactivated users. +* **Zero Access**: Cannot perform any actions or see any content. +* **Approval Required**: Must be promoted to `user` or `admin` by an existing Administrator. -Each group in Open WebUI contains: +:::note +The `admin` role effectively has `check_permission() == True` for everything. Granular permissions (like disabling "Web Search") generally do **not** apply to admins. +::: -- A unique identifier -- Name and description -- Owner/creator reference -- List of member user IDs -- Permission configuration -- Additional metadata +## Role Assignment -### Group Management +### Initial Setup +* **First User:** The very first account created on a fresh installation is automatically assigned the **Admin** role. +* **Subsequent Users:** New sign-ups are assigned the **Default User Role**. -Groups can be: +### Configuration +You can control the default role for new users via the `DEFAULT_USER_ROLE` environment variable: -- **Created manually** by administrators through the user interface -- **Synced automatically** from OAuth providers when `ENABLE_OAUTH_GROUP_MANAGEMENT` is enabled -- **Created automatically** from OAuth claims when both `ENABLE_OAUTH_GROUP_MANAGEMENT` and`ENABLE_OAUTH_GROUP_CREATION` - are enabled - -### OAuth Group Integration +```bash +DEFAULT_USER_ROLE=pending +# Options: 'pending', 'user', 'admin' +``` +* **pending (Recommended for public/shared instances):** New users cannot log in until an Admin explicitly activates them in the Admin Panel. +* **user:** New users get immediate access with default permissions. +* **admin:** (Use with caution) New users become full administrators. -When OAuth group management is enabled, user group memberships are synchronized with groups received in OAuth claims: +## Changing Roles +Administrators can change a user's role at any time via **Admin Panel > Users**. +* Promoting a user to `admin` grants them full control. +* Demoting an admin to `user` subjects them to the permission system again. -- Users are added to Open WebUI groups that match their OAuth claims -- Users are removed from groups not present in their OAuth claims -- With `ENABLE_OAUTH_GROUP_CREATION` enabled, groups from OAuth claims that don't exist in Open WebUI are automatically - created From d403cabfa0fa11049bf1ac8034b25c9e12fe9c74 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:15:28 +0100 Subject: [PATCH 31/66] update rbac --- docs/features/rbac/index.mdx | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/docs/features/rbac/index.mdx b/docs/features/rbac/index.mdx index 656d018bf..65b1cae68 100644 --- a/docs/features/rbac/index.mdx +++ b/docs/features/rbac/index.mdx @@ -3,9 +3,28 @@ sidebar_position: 100 title: "Role-Based Access Control (RBAC)" --- -## Access Control -- [‍🔑 Roles](./roles.md) - The roles defined in Open WebUI -- [‍🔐 Groups](./groups.md) - Setup groups of users to share access to resources -- [🔒 Permissions](./permissions.md) - Configure access controls and feature availability +Open WebUI implements a flexible and secure **Role-Based Access Control (RBAC)** system. This system allows administrators to precisely manage user capabilities and access to resources through three interconnected layers: -Roles, groups and permissions are designed to work together to provide a finegrained model for controlling user access to individual resources. +1. [**Roles**](./roles.md): The high-level user type (Admin, User, Pending). This defines the baseline trust level. +2. [**Permissions**](./permissions.md): Granular feature flags (e.g., "Can Delete Chats", "Can Use Web Search"). +3. [**Groups**](./groups.md): The mechanism for organizing users, granting additional permissions, and managing shared access to resources (ACLs). + +:::info Key Concept: Additive Permissions +The security model is **Additive**. Users start with their default rights, and Group memberships **add** capabilities. A user effectively has the *union* of all rights granted by their Roles and Groups. +::: + +## Documentation Guide + +* [‍🔑 **Roles**](./roles.md) + * Understand the difference between Admins and Users. + * Learn about Admin limitations and security/privacy configurations. + +* [🔒 **Permissions**](./permissions.md) + * Explore the full list of available permission toggles. + * Understand granular controls for Chat, Workspace, and Features. + * **Security Tip**: Learn how properly configured Global Defaults protect your system. + +* [‍🔐 **Groups**](./groups.md) + * Learn how to structure teams and projects. + * **Strategy**: Distinguish between "Permission Groups" (for rights) and "Sharing Groups" (for access). + * Manage Access Control Lists (ACLs) for private Models and Knowledge. From ac4b46ba7dc2cb9be654a2e903f526f5b548fc01 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:19:55 +0100 Subject: [PATCH 32/66] rem remnance --- .../advanced-topics/https-encryption.md | 10 +++++++--- docs/getting-started/advanced-topics/logging.md | 5 ----- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/getting-started/advanced-topics/https-encryption.md b/docs/getting-started/advanced-topics/https-encryption.md index 893117418..037840ed5 100644 --- a/docs/getting-started/advanced-topics/https-encryption.md +++ b/docs/getting-started/advanced-topics/https-encryption.md @@ -45,10 +45,14 @@ The best HTTPS solution depends on your existing infrastructure and technical ex - **Scalability and Performance:** Consider the performance and scalability needs of your Open WebUI instance when choosing a solution, especially for high-traffic deployments. - **Cost:** Some solutions (like cloud load balancers or Cloudflare's paid plans) may have associated costs. Let's Encrypt and many reverse proxies are free and open-source. -## 📚 Explore Deployment Tutorials for Step-by-Step Guides +## 📚 Explore HTTPS Tutorials -For detailed, practical instructions and community-contributed tutorials on setting up HTTPS encryption with various solutions, please visit the **[Deployment Tutorials](../../../tutorials/deployment/)** section. +We have dedicated step-by-step guides for setting up reverse proxies with HTTPS: -These tutorials often provide specific, step-by-step guides for different environments and HTTPS solutions, making the process easier to follow. +* **[Nginx](../../../tutorials/https/nginx.md)**: Industry-standard high-performance server. +* **[Caddy](../../../tutorials/https/caddy.md)**: Easiest setup with automatic HTTPS. +* **[HAProxy](../../../tutorials/https/haproxy.md)**: Robust load balancer and proxy. + +These tutorials provide specific configuration examples to get your secure Open WebUI instance running quickly. By implementing HTTPS, you significantly enhance the security and functionality of your Open WebUI instance, ensuring a safer and more feature-rich experience for yourself and your users. diff --git a/docs/getting-started/advanced-topics/logging.md b/docs/getting-started/advanced-topics/logging.md index ab818de11..ace9159c3 100644 --- a/docs/getting-started/advanced-topics/logging.md +++ b/docs/getting-started/advanced-topics/logging.md @@ -85,10 +85,5 @@ Setting `GLOBAL_LOG_LEVEL` configures the root logger in Python, affecting all l **Impact:** Setting `GLOBAL_LOG_LEVEL` to `DEBUG` will produce the most verbose logs, including detailed information that is helpful for development and troubleshooting. For production environments, `INFO` or `WARNING` might be more appropriate to reduce log volume. -:::note - -**Important Note:** Unlike `GLOBAL_LOG_LEVEL`, these app-specific variables might not affect logging from *all* third-party modules. They primarily control logging within Open WebUI's codebase. - -::: By understanding and utilizing these logging mechanisms, you can effectively monitor, debug, and gain insights into your Open WebUI instance. From 06dfffabfe38c3d8976eae28dbe0a34aa578be0d Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:22:10 +0100 Subject: [PATCH 33/66] Update https-encryption.md --- .../advanced-topics/https-encryption.md | 75 ++++++++++--------- 1 file changed, 40 insertions(+), 35 deletions(-) diff --git a/docs/getting-started/advanced-topics/https-encryption.md b/docs/getting-started/advanced-topics/https-encryption.md index 037840ed5..b24a44c75 100644 --- a/docs/getting-started/advanced-topics/https-encryption.md +++ b/docs/getting-started/advanced-topics/https-encryption.md @@ -5,54 +5,59 @@ title: "Enabling HTTPS Encryption" # Secure Your Open WebUI with HTTPS 🔒 -This guide explains how to enable HTTPS encryption for your Open WebUI instance. While **HTTPS is not strictly required** for basic operation, it's highly recommended for security and is **necessary for certain features like Voice Calls** to function in modern web browsers. +While **HTTPS is not strictly required** for basic local operation, it is **highly recommended** for all deployments and **mandatory** for enabling specific features like Voice Calls. + +:::warning Critical Feature Dependency +Modern browsers require a **Secure Context** (HTTPS) to access the microphone. +**Voice Calls will NOT work** if you access Open WebUI via `http://` (unless using `localhost`). +::: ## Why HTTPS Matters 🛡️ -HTTPS (Hypertext Transfer Protocol Secure) encrypts communication between your web browser and the Open WebUI server. This encryption provides several key benefits: +Enabling HTTPS encryption provides essential benefits: + +1. **🔒 Privacy & Security**: Encrypts all data between the user and the server, protecting chat history and credentials. +2. **🎤 Feature Unlocking**: Enables browser restrictions for Microphone (Voice Mode) and Camera access. +3. **💪 Integrity**: Ensures data is not tampered with in transit. +4. **✅ Trust**: Displays the padlock icon, reassuring users that the service is secure. -- **Privacy and Security:** Protects sensitive data like usernames, passwords, and chat content from eavesdropping and interception, especially on public networks. -- **Integrity:** Ensures that data transmitted between the browser and server is not tampered with during transit. -- **Feature Compatibility:** **Crucially, modern browsers block access to certain "secure context" features, such as microphone access for Voice Calls, unless the website is served over HTTPS.** -- **Trust and User Confidence:** HTTPS is indicated by a padlock icon in the browser address bar, building user trust and confidence in your Open WebUI deployment. +## Choosing Your Solution 🛠️ -**When is HTTPS Especially Important?** +The best method depends on your infrastructure. -- **Internet-Facing Deployments:** If your Open WebUI instance is accessible from the public internet, HTTPS is strongly recommended to protect against security risks. -- **Voice Call Feature:** If you plan to use the Voice Call feature in Open WebUI, HTTPS is **mandatory**. -- **Sensitive Data Handling:** If you are concerned about the privacy of user data, enabling HTTPS is a crucial security measure. +### 🏠 For Local/Docker Users +If you are running Open WebUI with Docker, the standard approach is to use a **Reverse Proxy**. This sits in front of Open WebUI and handles the SSL encryption. -## Choosing the Right HTTPS Solution for You 🛠️ +* **[Nginx](../../../tutorials/https/nginx.md)**: The industry standard. Highly configurable, great performance. +* **[Caddy](../../../tutorials/https/caddy.md)**: **Easiest option**. Automatically obtains and renews Let's Encrypt certificates with minimal config. +* **[HAProxy](../../../tutorials/https/haproxy.md)**: Robust choice for advanced load balancing needs. -The best HTTPS solution depends on your existing infrastructure and technical expertise. Here are some common and effective options: +### ☁️ For Cloud Deployments +* **Cloud Load Balancers**: (AWS ALB, Google Cloud Load Balancing) often handle SSL termination natively. +* **Cloudflare Tunnel**: Excellent for exposing localhost to the web securely without opening ports. -- **Cloud Providers (e.g., AWS, Google Cloud, Azure):** - - **Load Balancers:** Cloud providers typically offer managed load balancers (like AWS Elastic Load Balancer) that can handle HTTPS termination (encryption/decryption) for you. This is often the most straightforward and scalable approach in cloud environments. -- **Docker Container Environments:** - - **Reverse Proxies (Nginx, Traefik, Caddy):** Popular reverse proxies like Nginx, Traefik, and Caddy are excellent choices for managing HTTPS in Dockerized deployments. They can automatically obtain and renew SSL/TLS certificates (e.g., using Let's Encrypt) and handle HTTPS termination. - - **Nginx:** Highly configurable and widely used. - - **Traefik:** Designed for modern microservices and container environments, with automatic configuration and Let's Encrypt integration. - - **Caddy:** Focuses on ease of use and automatic HTTPS configuration. -- **Cloudflare:** - - **Simplified HTTPS:** Cloudflare provides a CDN (Content Delivery Network) and security services, including very easy HTTPS setup. It often requires minimal server-side configuration changes and is suitable for a wide range of deployments. -- **Ngrok:** - - **Local Development HTTPS:** Ngrok is a convenient tool for quickly exposing your local development server over HTTPS. It's particularly useful for testing features that require HTTPS (like Voice Calls) during development and for demos. **Not recommended for production deployments.** +### 🧪 For Development +* **Ngrok**: Good for quickly testing Voice features locally. *Not for production.* -**Key Considerations When Choosing:** +## 📚 Implementation Guides -- **Complexity:** Some solutions (like Cloudflare or Caddy) are simpler to set up than others (like manually configuring Nginx). -- **Automation:** Solutions like Traefik and Caddy offer automatic certificate management, which simplifies ongoing maintenance. -- **Scalability and Performance:** Consider the performance and scalability needs of your Open WebUI instance when choosing a solution, especially for high-traffic deployments. -- **Cost:** Some solutions (like cloud load balancers or Cloudflare's paid plans) may have associated costs. Let's Encrypt and many reverse proxies are free and open-source. +Ready to set it up? Check out our dedicated tutorial category for step-by-step configurations: -## 📚 Explore HTTPS Tutorials +
-We have dedicated step-by-step guides for setting up reverse proxies with HTTPS: + +

Nginx Setup

+

Manual control and high performance.

+ -* **[Nginx](../../../tutorials/https/nginx.md)**: Industry-standard high-performance server. -* **[Caddy](../../../tutorials/https/caddy.md)**: Easiest setup with automatic HTTPS. -* **[HAProxy](../../../tutorials/https/haproxy.md)**: Robust load balancer and proxy. + +

Caddy Setup

+

Zero-config automatic HTTPS.

+ -These tutorials provide specific configuration examples to get your secure Open WebUI instance running quickly. + +

📂 View All HTTPS Tutorials

+

Browse the full category of guides.

+ -By implementing HTTPS, you significantly enhance the security and functionality of your Open WebUI instance, ensuring a safer and more feature-rich experience for yourself and your users. +
From d5e001fde16865eb8e9842bbd50c294a3c8e8cc4 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:28:38 +0100 Subject: [PATCH 34/66] Update starting-with-functions.mdx --- .../quick-start/starting-with-functions.mdx | 31 ++++++++++++++++--- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/getting-started/quick-start/starting-with-functions.mdx b/docs/getting-started/quick-start/starting-with-functions.mdx index 74fa12817..a44aab175 100644 --- a/docs/getting-started/quick-start/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/starting-with-functions.mdx @@ -22,11 +22,23 @@ Pipe Functions are “bring-your-own-model (or tool)” plugins: ## Step 1: Find a Pipe Function to Try -Let’s integrate **Anthropic** with Open WebUI—even though Anthropic only supports its own native API (not OpenAI-compatible endpoints)! +Functions are powerful tools, and the community has created thousands of them! You can browse, search, and import them directly from our community hub. -1. Go to the [Anthropic Chat function page](https://openwebui.com/f/justinrahb/anthropic). +:::info Community Account Required +To search and import functions directly from **[Open WebUI Community](https://openwebui.com/search)**, you must be logged in with a registered community account. +::: -2. Click **Get**. +1. Go to **[Open WebUI Community Search](https://openwebui.com/search)** (or browse `https://openwebui.com/functions`). +2. Explore the library! You can find functions for: + * **New Providers**: Anthropic, Google Gemini, Groq. + * **Tools**: Web Search, Calculator, Home Assistant control. + * **Utilities**: Auto-tagging, content filtering, and more. +3. **Pro Tip**: Even if you don't find exactly what you need, you can use existing functions as **templates** to build your own! + +For this guide, let's try integrating **Anthropic** (Claude models): + +1. Locate the [Anthropic Pipe](https://openwebui.com/f/justinrahb/anthropic) function. +2. Click **Get**. ![Anthropic Pipe Function Page](/images/getting-started/pipe-anthropic-function.png) @@ -86,7 +98,16 @@ Some functions need credentials (like Anthropic’s API key): ### Next Steps & Learn More -- [Pipe Functions Guide](https://docs.openwebui.com/features/plugin/functions/pipe) -- [Browse community functions](https://openwebui.com/functions) +### Next Steps & Learn More + +Ready to build your own? Check out our detailed development guides: + +* **[Functions Overview](../../../features/plugin/functions/index.mdx)**: Learn the basics of the Functions system. +* **[Pipes Guide](../../../features/plugin/functions/pipe.mdx)**: Create custom model providers and logic pipelines. +* **[Filters Guide](../../../features/plugin/functions/filter.mdx)**: Intercept and modify messages (Input/Output guards). +* **[Actions Guide](../../../features/plugin/functions/action.mdx)**: Add buttons/actions to messages. +* **[Tools Guide](../../../features/plugin/tools/index.mdx)**: Build tools for LLMs to use (RAG, APIs). + +* **[Community Registry](https://openwebui.com/search)**: Browse hundreds of community-made functions. 🚀 With Pipe Functions, your Open WebUI is limited *only by your imagination*! \ No newline at end of file From c27e418eb933bebbde62cf8e4f362e42b94dca9b Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:34:54 +0100 Subject: [PATCH 35/66] Update starting-with-openai.mdx --- .../quick-start/starting-with-openai.mdx | 46 ++++++++++++++++--- 1 file changed, 40 insertions(+), 6 deletions(-) diff --git a/docs/getting-started/quick-start/starting-with-openai.mdx b/docs/getting-started/quick-start/starting-with-openai.mdx index b07c30174..dada9c594 100644 --- a/docs/getting-started/quick-start/starting-with-openai.mdx +++ b/docs/getting-started/quick-start/starting-with-openai.mdx @@ -30,6 +30,9 @@ Other providers use different URLs — check your provider’s documentation. --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + ## Step 2: Add the API Connection in Open WebUI Once Open WebUI is running: @@ -37,15 +40,46 @@ Once Open WebUI is running: 1. Go to the ⚙️ **Admin Settings**. 2. Navigate to **Connections > OpenAI > Manage** (look for the wrench icon). 3. Click ➕ **Add New Connection**. -4. Fill in the following: - - API URL: https://api.openai.com/v1 (or the URL of your specific provider) - - API Key: Paste your key here -5. Click Save ✅. + + + + Use this for **OpenAI**, **DeepSeek**, **OpenRouter**, **LocalAI**, **FastChat**, **Helicone**, **LiteLLM**, etc. + + * **Connection Type**: External + * **URL**: `https://api.openai.com/v1` (or your provider's endpoint) + * **API Key**: Your secret key (usually starts with `sk-...`) + + + + + For Microsoft Azure OpenAI deployments. + + 1. Find **Provider Type** and click the button labeled **OpenAI** to switch it to **Azure OpenAI**. + 2. **URL**: Your Azure Endpoint (e.g., `https://my-resource.openai.azure.com`). + 3. **API Version**: e.g., `2024-02-15-preview`. + 4. **API Key**: Your Azure API Key. + 5. **Model IDs (Deployments)**: You **must** add your specific Deployment Names here (e.g., `my-gpt4-deployment`). + + + + +### Advanced Configuration + +* **Model IDs (Filter)**: + * *Default (Empty)*: Auto-detects all available models from the provider. + * *Set*: Acts as an **Allowlist**. Only the specific model IDs you enter here will be visible to users. Use this to hide older or expensive models. + + :::tip OpenRouter Recommendation + When using **OpenRouter**, we **highly recommend** using this allowlist (adding specific Model IDs). OpenRouter exposes thousands of models, which can clutter your model selector and slow down the admin panel if not filtered. + ::: + +* **Prefix ID**: + * If you connect multiple providers that have models with the same name (e.g., two providers both offering `llama3`), add a prefix here (e.g., `groq/`) to distinguish them. The model will appear as `groq/llama3`. -This securely stores your credentials and sets up the connection. +4. Click **Save** ✅. -Here’s what it looks like: +This securely stores your credentials. ![OpenAI Connection Screen](/images/getting-started/quick-start/manage-openai.png) From ec6c9681e8691e55a08731c26cb93336c3959fec Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:44:03 +0100 Subject: [PATCH 36/66] tutorials getting started --- .../quick-start/starting-with-llama-cpp.mdx | 12 ++++++------ .../quick-start/starting-with-ollama.mdx | 11 +++++++++++ .../quick-start/starting-with-openai-compatible.mdx | 13 +++++++------ .../quick-start/starting-with-vllm.mdx | 8 +++++--- 4 files changed, 29 insertions(+), 15 deletions(-) diff --git a/docs/getting-started/quick-start/starting-with-llama-cpp.mdx b/docs/getting-started/quick-start/starting-with-llama-cpp.mdx index 8e19312c7..aa5284a42 100644 --- a/docs/getting-started/quick-start/starting-with-llama-cpp.mdx +++ b/docs/getting-started/quick-start/starting-with-llama-cpp.mdx @@ -95,12 +95,12 @@ http://127.0.0.1:10000 To control and query your locally running model directly from Open WebUI: 1. Open Open WebUI in your browser -2. Go to ⚙️ Admin Settings → Connections → OpenAI Connections -3. Click ➕ Add Connection and enter: - -- URL: `http://127.0.0.1:10000/v1` - (Or use `http://host.docker.internal:10000/v1` if running WebUI inside Docker) -- API Key: `none` (leave blank) +2. Go to ⚙️ **Admin Settings → Connections → OpenAI**. +3. Click ➕ **Add Connection**. +4. Set the following (under **Standard / Compatible** if tabs are visible): + - **URL**: `http://127.0.0.1:10000/v1` + (Or use `http://host.docker.internal:10000/v1` if running WebUI inside Docker. **Note the `/v1` at the end!**) + - **API Key**: `none` (leave blank or type specific key if configured) 💡 Once saved, Open WebUI will begin using your local Llama.cpp server as a backend! diff --git a/docs/getting-started/quick-start/starting-with-ollama.mdx b/docs/getting-started/quick-start/starting-with-ollama.mdx index 1f2ff78f5..63d280c5d 100644 --- a/docs/getting-started/quick-start/starting-with-ollama.mdx +++ b/docs/getting-started/quick-start/starting-with-ollama.mdx @@ -25,6 +25,17 @@ To manage your Ollama instance in Open WebUI, follow these steps: 2. Navigate to **Connections > Ollama > Manage** (click the wrench icon). From here, you can download models, configure settings, and manage your connection to Ollama. +### Connection Tips + +* **Docker Users**: If Ollama is running on your host machine, use `http://host.docker.internal:11434` as the URL. +* **Load Balancing**: You can add **multiple** Ollama instances. Open WebUI will distribute requests between them using a **random selection** strategy, providing basic load balancing for concurrent users. + * **Note**: To enable this, ensure the **Model IDs match exactly** across instances. If you use **Prefix IDs**, they must be identical (or empty) for the models to merge into a single entry. + +### Advanced Configuration + +* **Prefix ID**: If you have multiple Ollama instances serving the same model names, use a prefix (e.g., `remote/`) to distinguish them. +* **Model IDs (Filter)**: Make specific models visible by listing them here (whitelist). Leave empty to show all. + Here’s what the management screen looks like: ![Ollama Management Screen](/images/getting-started/quick-start/manage-ollama.png) diff --git a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx index a1e30d948..284cfd020 100644 --- a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx +++ b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx @@ -48,13 +48,14 @@ See [their docs](https://lemonade-server.ai/) for details. ## Step 2: Connect Your Server to Open WebUI 1. Open Open WebUI in your browser. -2. Go to ⚙️ **Admin Settings** → **Connections** → **OpenAI Connections**. +2. Go to ⚙️ **Admin Settings** → **Connections** → **OpenAI**. 3. Click ➕ **Add Connection**. - - - **URL**: Use your server’s API endpoint (for example, `http://localhost:11434/v1` for Ollama, or your own Llama.cpp server’s address). - - **API Key**: Leave blank unless required. - -4. Click Save. +4. Select the **Standard / Compatible** tab (if available). +5. Fill in the following: + - **API URL**: Use your server’s API endpoint. + * **Examples**: `http://localhost:11434/v1` (Ollama), `http://localhost:10000/v1` (Llama.cpp). + - **API Key**: Leave blank unless the server requires one. +6. Click **Save**. :::tip diff --git a/docs/getting-started/quick-start/starting-with-vllm.mdx b/docs/getting-started/quick-start/starting-with-vllm.mdx index 6a6483ea8..53aa96946 100644 --- a/docs/getting-started/quick-start/starting-with-vllm.mdx +++ b/docs/getting-started/quick-start/starting-with-vllm.mdx @@ -26,10 +26,12 @@ For remote servers, use the appropriate hostname or IP address. 1. Go to ⚙️ **Admin Settings**. 2. Navigate to **Connections > OpenAI > Manage** (look for the wrench icon). 3. Click ➕ **Add New Connection**. -4. Fill in the following: +4. Select the **Standard / Compatible** tab (if available). +5. Fill in the following: - **API URL**: `http://localhost:8000/v1` (or your vLLM server URL) - - **API Key**: Leave empty (vLLM typically doesn't require an API key for local connections) -5. Click **Save**. + * **Docker Users**: Use `http://host.docker.internal:8000/v1` if Open WebUI is in a container. + - **API Key**: `none` (or leave empty if no key is configured) +6. Click **Save**. --- From 206f56a4e62274f41966678813c91b1ac35038e2 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:46:12 +0100 Subject: [PATCH 37/66] Update api-endpoints.md --- docs/getting-started/api-endpoints.md | 19 +++++++++++++++---- 1 file changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/api-endpoints.md b/docs/getting-started/api-endpoints.md index 5a56a3a98..74b068a11 100644 --- a/docs/getting-started/api-endpoints.md +++ b/docs/getting-started/api-endpoints.md @@ -91,7 +91,10 @@ If you want to interact directly with Ollama models—including for embedding ge #### 🔁 Generate Completion (Streaming) ```bash -curl http://localhost:3000/ollama/api/generate -d '{ +curl http://localhost:3000/ollama/api/generate \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ "model": "llama3.2", "prompt": "Why is the sky blue?" }' @@ -100,18 +103,26 @@ curl http://localhost:3000/ollama/api/generate -d '{ #### 📦 List Available Models ```bash -curl http://localhost:3000/ollama/api/tags +curl http://localhost:3000/ollama/api/tags \ + -H "Authorization: Bearer YOUR_API_KEY" ``` #### 🧠 Generate Embeddings ```bash -curl -X POST http://localhost:3000/ollama/api/embed -d '{ +curl -X POST http://localhost:3000/ollama/api/embed \ + -H "Authorization: Bearer YOUR_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ "model": "llama3.2", - "input": ["Open WebUI is great!", "Let's generate embeddings."] + "input": ["Open WebUI is great!", "Let'\''s generate embeddings."] }' ``` +:::info +When using the Ollama Proxy endpoints, you **must** include the `Content-Type: application/json` header for POST requests, or the API may fail to parse the body. Authorization headers are also required if your instance is secured. +::: + This is ideal for building search indexes, retrieval systems, or custom pipelines using Ollama models behind the Open WebUI. ### 🧩 Retrieval Augmented Generation (RAG) From 926569acd849b8ef22ba25ba007257728711c083 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:48:26 +0100 Subject: [PATCH 38/66] Update improve-performance-local.md --- docs/tutorials/tips/improve-performance-local.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/tutorials/tips/improve-performance-local.md b/docs/tutorials/tips/improve-performance-local.md index a0b0280b7..a52944bd1 100644 --- a/docs/tutorials/tips/improve-performance-local.md +++ b/docs/tutorials/tips/improve-performance-local.md @@ -52,6 +52,9 @@ Follow these steps to configure an efficient task model: - **Hosted API Endpoint (For Maximum Speed)** - Connect to a hosted API service to handle task processing. - This can be very cheap. For example, OpenRouter offers Llama and Qwen models at less than **1.5 cents per million input tokens**. + :::tip OpenRouter Recommendation + When using **OpenRouter**, we highly recommend configuring the **Model IDs (Allowlist)** in the connection settings. Importing thousands of models can clutter your selector and degrade admin panel performance. + ::: - **Disable Unnecessary Automation** - If certain automated features are not required, disable them to reduce extraneous background calls—especially features like autocomplete. From c7e91b0ff372dca1fc26a00e326f5c003d985e41 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:51:13 +0100 Subject: [PATCH 39/66] Create autocomplete.md --- docs/features/chat-features/autocomplete.md | 66 +++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/features/chat-features/autocomplete.md diff --git a/docs/features/chat-features/autocomplete.md b/docs/features/chat-features/autocomplete.md new file mode 100644 index 000000000..be1bde7c4 --- /dev/null +++ b/docs/features/chat-features/autocomplete.md @@ -0,0 +1,66 @@ +--- +sidebar_position: 10 +title: "Autocomplete" +--- + +# ✨ Autocomplete + +Open WebUI offers an **AI-powered Autocomplete** feature that suggests text completions in real-time as you type your prompt. It acts like a "Copilot" for your chat input, helping you craft prompts faster using your configured task model. + +![Autocomplete Example](/images/features/autocomplete-example.png) + +## How It Works + +When enabled, Open WebUI monitors your input in the chat box. When you pause typing, it sends your current text to a lightweight **Task Model**. This model predicts the likely next words or sentences, which appear as "ghost text" overlaying your input. + +- **Accept Suggestion**: Press `Tab` (or the `Right Arrow` key) to accept the suggestion. +- **Reject/Ignore**: Simply keep typing to overwrite the suggestion. + +:::info +Autocomplete functionality relies heavily on the response speed of your **Task Model**. We recommend using a small, fast model (e.g., `Llama 3.2 3B`, `Qwen 2.5 3B`, or `GPT-4o-mini`) to ensure suggestions appear instantly. +::: + +## Configuration + +The Autocomplete feature is controlled by a two-layer system: **Global** availability and **User** preference. + +### 1. Global Configuration (Admin) + +Admins control whether the autocomplete feature is available on the server. + +- **Option 1: Admin Panel** + Go to **Admin Settings > Interface > Task Model** and toggle **Autocomplete Generation**. + +- **Option 2: Environment Variable** + Set the following environment variable to `True` (default is `False` in some versions, or `True` in others depending on release). + + ```bash + ENABLE_AUTOCOMPLETE_GENERATION=True + ``` + +### 2. User Configuration (Personal) + +Even if enabled globally, individual users can turn it off for themselves if they find it distracting. + +- Go to **Settings > Interface**. +- Toggle **Autocomplete Generation**. + +:::note +If the Admin has disabled Autocomplete globally, users will **not** be able to enable it in their personal settings. +::: + +## Performance & Troubleshooting + +### Why aren't suggestions appearing? +1. **Check Settings**: Ensure it is enabled in **both** Admin and User settings. +2. **Task Model**: Go to **Admin Settings > Interface** and verify a **Task Model** is selected. If no model is selected, the feature cannot generate predictions. +3. **Latency**: If your Task Model is large or running on slow hardware, predictions might arrive too late to be useful. Switch to a smaller model. + +### Performance Impact +Autocomplete sends a request to your LLM essentially every time you pause typing (debounced). +- **Local Models**: This can consume significant GPU/CPU resources on the host machine. +- **API Providers**: This will generate a high volume of API calls (though usually with very short token counts). + +:::warning +For multi-user instances running on limited local hardware, we recommend **disabling** Autocomplete to prioritize resources for actual chat generation. +::: From 227808f251d308bb4c782320aec0dd209c257859 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:57:29 +0100 Subject: [PATCH 40/66] update --- docs/features/chat-features/autocomplete.md | 30 ++++++++++++--------- docs/features/chat-features/index.mdx | 2 ++ docs/getting-started/env-configuration.mdx | 20 ++++++++++++++ 3 files changed, 39 insertions(+), 13 deletions(-) diff --git a/docs/features/chat-features/autocomplete.md b/docs/features/chat-features/autocomplete.md index be1bde7c4..8c8585e63 100644 --- a/docs/features/chat-features/autocomplete.md +++ b/docs/features/chat-features/autocomplete.md @@ -7,8 +7,6 @@ title: "Autocomplete" Open WebUI offers an **AI-powered Autocomplete** feature that suggests text completions in real-time as you type your prompt. It acts like a "Copilot" for your chat input, helping you craft prompts faster using your configured task model. -![Autocomplete Example](/images/features/autocomplete-example.png) - ## How It Works When enabled, Open WebUI monitors your input in the chat box. When you pause typing, it sends your current text to a lightweight **Task Model**. This model predicts the likely next words or sentences, which appear as "ghost text" overlaying your input. @@ -17,7 +15,17 @@ When enabled, Open WebUI monitors your input in the chat box. When you pause typ - **Reject/Ignore**: Simply keep typing to overwrite the suggestion. :::info -Autocomplete functionality relies heavily on the response speed of your **Task Model**. We recommend using a small, fast model (e.g., `Llama 3.2 3B`, `Qwen 2.5 3B`, or `GPT-4o-mini`) to ensure suggestions appear instantly. +**Performance Recommendation** + +Autocomplete functionality relies heavily on the response speed of your **Task Model**. We recommend using a small, fast, **non-reasoning** model to ensure suggestions appear instantly. + +**Recommended Models:** +- **Llama 3.2** (1B or 3B) +- **Qwen 3** (0.6B or 3B) +- **Gemma 3** (1B or 4B) +- **GPT-5 Nano** (Optimized for low latency) + +Avoid using "Reasoning" models (e.g., o1, o3) or heavy Chain-of-Thought models for this feature, as the latency will make the autocomplete experience sluggish. ::: ## Configuration @@ -28,15 +36,10 @@ The Autocomplete feature is controlled by a two-layer system: **Global** availab Admins control whether the autocomplete feature is available on the server. -- **Option 1: Admin Panel** - Go to **Admin Settings > Interface > Task Model** and toggle **Autocomplete Generation**. - -- **Option 2: Environment Variable** - Set the following environment variable to `True` (default is `False` in some versions, or `True` in others depending on release). - - ```bash - ENABLE_AUTOCOMPLETE_GENERATION=True - ``` +### 1. Configuring Autocomplete (Global) + +**Admin Panel Settings:** +Go to **Admin Settings > Interface > Task Model** and toggle **Autocomplete Generation**. ### 2. User Configuration (Personal) @@ -55,11 +58,12 @@ If the Admin has disabled Autocomplete globally, users will **not** be able to e 1. **Check Settings**: Ensure it is enabled in **both** Admin and User settings. 2. **Task Model**: Go to **Admin Settings > Interface** and verify a **Task Model** is selected. If no model is selected, the feature cannot generate predictions. 3. **Latency**: If your Task Model is large or running on slow hardware, predictions might arrive too late to be useful. Switch to a smaller model. +4. **Reasoning Models**: Ensure you are **not** using a "Reasoning" model (like o1 or o3), as their internal thought process creates excessive latency that breaks real-time autocomplete. ### Performance Impact Autocomplete sends a request to your LLM essentially every time you pause typing (debounced). - **Local Models**: This can consume significant GPU/CPU resources on the host machine. -- **API Providers**: This will generate a high volume of API calls (though usually with very short token counts). +- **API Providers**: This will generate a high volume of API calls (though usually with very short token counts). Be mindful of your provider's **Rate Limits** (Requests Per Minute/RPM and Tokens Per Minute/TPM) to avoid interruptions. :::warning For multi-user instances running on limited local hardware, we recommend **disabling** Autocomplete to prioritize resources for actual chat generation. diff --git a/docs/features/chat-features/index.mdx b/docs/features/chat-features/index.mdx index 93501123d..437c10f9f 100644 --- a/docs/features/chat-features/index.mdx +++ b/docs/features/chat-features/index.mdx @@ -15,4 +15,6 @@ Open WebUI provides a comprehensive set of chat features designed to enhance you - **[⚙️ Chat Parameters](./chat-params.md)**: Control system prompts and advanced parameters at different levels (per-chat, per-account, or per-model). +- **[✨ Autocomplete](./autocomplete.md)**: AI-powered text prediction that helps you write prompts faster using a task model. + - **[🗨️ Chat Sharing](./chatshare.md)**: Share conversations locally or via the Open WebUI Community platform with controllable privacy settings. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index bbb341fd4..8273ea022 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2600,6 +2600,26 @@ If you are embedding externally via API, ensure your rate limits are high enough - Description: Sets the timeout in seconds for external reranker API requests during RAG document retrieval. Leave empty to use default timeout behavior. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `RAG_EXTERNAL_RERANKER_URL` + +- Type: `str` +- Default: Empty string (' ') +- Description: Sets the **full URL** for the external reranking API. +- Persistence: This environment variable is a `PersistentConfig` variable. + +:::warning + +You **MUST** provide the full URL, including the endpoint path (e.g., `https://api.yourprovider.com/v1/rerank`). The system does **not** automatically append `/v1/rerank` or any other path to the base URL you provide. + +::: + +#### `RAG_EXTERNAL_RERANKER_API_KEY` + +- Type: `str` +- Default: Empty string (' ') +- Description: Sets the API key for the external reranking API. +- Persistence: This environment variable is a `PersistentConfig` variable. + ### Query Generation #### `ENABLE_RETRIEVAL_QUERY_GENERATION` From 2492343ce4e0a0bf46927dfaf911e13f11c5a5e9 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 20:58:59 +0100 Subject: [PATCH 41/66] Update scim.mdx --- docs/features/auth/scim.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/features/auth/scim.mdx b/docs/features/auth/scim.mdx index bc49d481b..db6a4cb5f 100644 --- a/docs/features/auth/scim.mdx +++ b/docs/features/auth/scim.mdx @@ -191,4 +191,4 @@ SCIM works best when combined with SSO (Single Sign-On). A typical setup include This ensures users are automatically created and can immediately authenticate using their corporate credentials. -For SSO configuration, see the [SSO documentation](https://docs.openwebui.com/features/auth/). +For SSO configuration, see the [SSO documentation](https://docs.openwebui.com/features/auth/sso/). From 80d6b78caa4a83abe30147f72b44fa588b0c6cb3 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:01:56 +0100 Subject: [PATCH 42/66] webui secret key --- docs/faq.mdx | 8 ++++++++ docs/features/mcp.mdx | 4 ++++ .../features/plugin/tools/openapi-servers/mcp.mdx | 4 ++++ docs/getting-started/env-configuration.mdx | 15 +++++++++++++-- docs/tutorials/integrations/mcp-notion.mdx | 5 +++++ 5 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/faq.mdx b/docs/faq.mdx index c0ea4571a..bc4b0bcab 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -84,6 +84,14 @@ Everything you need to run Open WebUI, including your data, remains within your **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 I'm being logged out, or getting "Error decrypting tokens" for my tools? + +**A:** This happens because you haven't set a persistent `WEBUI_SECRET_KEY` in your environment variables. +* **Logouts:** Without this key, Open WebUI generates a random one every time it starts. This invalidates your previous session cookies (JWTs), forcing you to log in again. +* **Decryption Errors:** Essential secrets (like OAuth tokens for MCP tools or API keys) are encrypted using this key. If the key changes on restart, Open WebUI cannot decrypt them, leading to errors. + +**Fix:** Set `WEBUI_SECRET_KEY` to a constant, secure string in your Docker Compose or environment config. + ### 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. diff --git a/docs/features/mcp.mdx b/docs/features/mcp.mdx index 6ca6d5e22..558395115 100644 --- a/docs/features/mcp.mdx +++ b/docs/features/mcp.mdx @@ -9,6 +9,10 @@ Open WebUI natively supports **MCP (Model Context Protocol)** starting in **v0.6 Requires **Open WebUI v0.6.31+**. ::: +:::danger Prerequisite: WEBUI_SECRET_KEY +You **MUST** set the `WEBUI_SECRET_KEY` environment variable in your Docker setup. Without it, **OAuth-connected MCP tools (like Notion)** will **break** every time you restart or recreate the container (Error: `Error decrypting tokens`), forcing you to re-authenticate everything. +::: + ## 🚀 Quick start 1. Open **⚙️ Admin Settings → External Tools**. diff --git a/docs/features/plugin/tools/openapi-servers/mcp.mdx b/docs/features/plugin/tools/openapi-servers/mcp.mdx index 20dbea48a..aeb6c0eaf 100644 --- a/docs/features/plugin/tools/openapi-servers/mcp.mdx +++ b/docs/features/plugin/tools/openapi-servers/mcp.mdx @@ -5,6 +5,10 @@ title: "MCP Support" This documentation explains how to easily set up and deploy the [**MCP (Model Context Protocol)-to-OpenAPI proxy server** (mcpo)](https://github.com/open-webui/mcpo) provided by Open WebUI. Learn how you can effortlessly expose MCP-based tool servers using standard, familiar OpenAPI endpoints suitable for end-users and developers. +:::danger Critical for Persistence +If you connect Open WebUI to this proxy using an API Key or Auth Token, you **MUST** set `WEBUI_SECRET_KEY` in your Open WebUI Docker config. If this key changes (e.g., on container restart), Open WebUI will fail to decrypt the stored credentials for your tool. +::: + ### 📌 What is the MCP Proxy Server? The MCP-to-OpenAPI proxy server lets you use tool servers implemented with MCP (Model Context Protocol) directly via standard REST/OpenAPI APIs—no need to manage unfamiliar or complicated custom protocols. If you're an end-user or application developer, this means you can interact easily with powerful MCP-based tooling directly through familiar REST-like endpoints. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 8273ea022..580a658ca 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -1255,9 +1255,20 @@ Invalid regex patterns will cause password validation to fail, potentially preve - Type: `str` - Default: `t0p-s3cr3t` - Docker Default: Randomly generated on first start -- Description: Overrides the randomly generated string used for JSON Web Token. +- Description: Overrides the randomly generated string used for JSON Web Token and **encryption of sensitive data** (like OAuth tokens for MCP). -:::warning +:::danger Critical for Docker/Production + +You **MUST** set `WEBUI_SECRET_KEY` to a secure, persistent value. + +If you do NOT set this: +1. It will be randomly generated each time the container restarts/recreates. +2. **All OAuth sessions will become invalid.** +3. **MCP Tools will break** (Error: `Error decrypting tokens`) because they cannot decrypt the tokens stored with the previous key. +4. You will be logged out. + +**Do not leave this unset in production.** +::: **Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS** diff --git a/docs/tutorials/integrations/mcp-notion.mdx b/docs/tutorials/integrations/mcp-notion.mdx index ce0111f54..ce9ae0e72 100644 --- a/docs/tutorials/integrations/mcp-notion.mdx +++ b/docs/tutorials/integrations/mcp-notion.mdx @@ -27,6 +27,11 @@ This method connects directly to Notion's hosted MCP endpoint (`https://mcp.noti **Streamable HTTP** is preferred for its simplicity and enhanced security. It handles authentication via Notion's official OAuth flow, meaning you do not need to manually manage secrets or integration tokens. ::: +:::danger Critical for OAuth Persistence +You **MUST** set the `WEBUI_SECRET_KEY` environment variable in your Docker setup to a persistent value. +If you do not, your Notion OAuth session will become invalid every time you restart the container, forcing you to re-authenticate repeatedly. +::: + ### 1. Configure Tool You can automatically prefill the connection settings by importing the JSON configuration below. From 3a616e2a70a61b0ec87b70fb698ea7e67c84fd07 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:06:39 +0100 Subject: [PATCH 43/66] podman --- docs/getting-started/quick-start/index.mdx | 7 ++ .../quick-start/tab-docker/Podman.md | 28 ++++++-- .../quick-start/tab-docker/PodmanQuadlet.md | 68 +++++++++++++++++++ docs/troubleshooting/connection-error.mdx | 8 +-- 4 files changed, 101 insertions(+), 10 deletions(-) create mode 100644 docs/getting-started/quick-start/tab-docker/PodmanQuadlet.md diff --git a/docs/getting-started/quick-start/index.mdx b/docs/getting-started/quick-start/index.mdx index 1cf8dbe40..91195bb66 100644 --- a/docs/getting-started/quick-start/index.mdx +++ b/docs/getting-started/quick-start/index.mdx @@ -10,6 +10,7 @@ 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 PodmanQuadlet from './tab-docker/PodmanQuadlet.md'; import PodmanKubePlay from './tab-docker/PodmanKubePlay.md'; import ManualDocker from './tab-docker/ManualDocker.md'; import DockerSwarm from './tab-docker/DockerSwarm.md'; @@ -68,6 +69,12 @@ Choose your preferred installation method below:
+ +
+ +
+ +
diff --git a/docs/getting-started/quick-start/tab-docker/Podman.md b/docs/getting-started/quick-start/tab-docker/Podman.md index 99395435d..90f7edefd 100644 --- a/docs/getting-started/quick-start/tab-docker/Podman.md +++ b/docs/getting-started/quick-start/tab-docker/Podman.md @@ -19,16 +19,32 @@ Podman is a daemonless container engine for developing, managing, and running OC ## Networking with Podman -If networking issues arise, use slirp4netns to adjust the pod's network settings to allow the container to access your computer's ports. +If networking issues arise (specifically on rootless Podman), you may need to adjust the network bridge settings. -Ensure you have [slirp4netns installed](https://github.com/rootless-containers/slirp4netns?tab=readme-ov-file#install), remove the previous container if it exists using `podman rm`, and start a new container with +:::warning Slirp4netns Deprecation +Older Podman instructions often recommended `slirp4netns`. However, `slirp4netns` is being **deprecated** and will be removed in **Podman 6**. + +The modern successor is **[pasta](https://passt.top/passt/about/)**, which is the default in Podman 5.0+. +::: + +### Accessing the Host (Local Services) + +If you are running Ollama or other services directly on your host machine, use the special DNS name **`host.containers.internal`** to point to your computer. + +#### Modern Approach (Pasta - Default in Podman 5+) +No special flags are usually needed to access the host via `host.containers.internal`. + +#### Legacy Approach (Slirp4netns) +If you are on an older version of Podman and `pasta` is not available: +1. Ensure you have [slirp4netns installed](https://github.com/rootless-containers/slirp4netns). +2. Start the container with the following flag to allow host loopback: ```bash - podman run -d --network=slirp4netns:allow_host_loopback=true --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main +podman run -d --network=slirp4netns:allow_host_loopback=true --name openwebui -p 3000:8080 -v open-webui:/app/backend/data ghcr.io/open-webui/open-webui:main ``` -If you are using Ollama from your computer (not running inside a container), - -Once inside open-webui, navigate to Settings > Admin Settings > Connections and create a new Ollama API connection to `http://10.0.2.2:[OLLAMA PORT]`. By default, the Ollama port is 11434. +### Connection Configuration +Once inside Open WebUI, navigate to **Settings > Admin Settings > Connections** and set your Ollama API connection to: +`http://host.containers.internal:11434` Refer to the Podman [documentation](https://podman.io/) for advanced configurations. diff --git a/docs/getting-started/quick-start/tab-docker/PodmanQuadlet.md b/docs/getting-started/quick-start/tab-docker/PodmanQuadlet.md new file mode 100644 index 000000000..f40a91db3 --- /dev/null +++ b/docs/getting-started/quick-start/tab-docker/PodmanQuadlet.md @@ -0,0 +1,68 @@ +# Podman Quadlets (systemd) + +Podman Quadlets allow you to manage containers as native systemd services. This is the recommended way to run production containers on Linux distributions that use systemd (like Fedora, RHEL, Ubuntu, etc.). + +## 🛠️ Setup + +1. **Create the configuration directory:** + For a rootless user deployment: + ```bash + mkdir -p ~/.config/containers/systemd/ + ``` + +2. **Create the container file:** + Create a file named `~/.config/containers/systemd/open-webui.container` with the following content: + + ```ini title="open-webui.container" + [Unit] + Description=Open WebUI Container + After=network-online.target + + [Container] + Image=ghcr.io/open-webui/open-webui:main + ContainerName=open-webui + PublishPort=3000:8080 + Volume=open-webui:/app/backend/data + + # Networking: Pasta is used by default in Podman 5+ + # If you need to access host services (like Ollama on the host): + AddHost=host.containers.internal:host-gateway + + [Service] + Restart=always + + [Install] + WantedBy=default.target + ``` + +3. **Reload systemd and start the service:** + ```bash + systemctl --user daemon-reload + systemctl --user start open-webui + ``` + +4. **Enable auto-start on boot:** + ```bash + systemctl --user enable open-webui + ``` + +## 📊 Management + +- **Check status:** + ```bash + systemctl --user status open-webui + ``` + +- **View logs:** + ```bash + journalctl --user -u open-webui -f + ``` + +- **Stop service:** + ```bash + systemctl --user stop open-webui + ``` + +:::tip Updating +To update the image, simply pull the new version (`podman pull ghcr.io/open-webui/open-webui:main`) and restart the service (`systemctl --user restart open-webui`). +::: diff --git a/docs/troubleshooting/connection-error.mdx b/docs/troubleshooting/connection-error.mdx index 9853b67b9..4676f30b4 100644 --- a/docs/troubleshooting/connection-error.mdx +++ b/docs/troubleshooting/connection-error.mdx @@ -160,14 +160,14 @@ docker run -d -p 3000:8080 -e HF_ENDPOINT=https://hf-mirror.com/ --add-host=host Running on MacOS with Podman? Here’s how to ensure connectivity: -1. **Enable Host Loopback**: - Use `--network slirp4netns:allow_host_loopback=true` in your command. +1. **Enable Host Access**: + Podman 5.0+ uses **pasta** by default, which simplifies host loopback. If you are on an older version, you may need `--network slirp4netns:allow_host_loopback=true`. 2. **Set OLLAMA_BASE_URL**: - Ensure it points to `http://host.containers.internal:11434`. + Ensure it points to **`http://host.containers.internal:11434`**. **Example Podman Command**: ```bash -podman run -d --network slirp4netns:allow_host_loopback=true -p 3000:8080 -e OLLAMA_BASE_URL=http://host.containers.internal:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main +podman run -d -p 3000:8080 -e OLLAMA_BASE_URL=http://host.containers.internal:11434 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main ``` From e5a2f0b61dac7d9b88f03d6992b3baed3bd15692 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:10:51 +0100 Subject: [PATCH 44/66] oauth --- docs/features/auth/sso/index.mdx | 11 ++-- .../tips/dual-oauth-configuration.mdx | 64 +++++++++++++++++++ 2 files changed, 71 insertions(+), 4 deletions(-) create mode 100644 docs/tutorials/tips/dual-oauth-configuration.mdx diff --git a/docs/features/auth/sso/index.mdx b/docs/features/auth/sso/index.mdx index 0e7d9f748..f6dbb3f55 100644 --- a/docs/features/auth/sso/index.mdx +++ b/docs/features/auth/sso/index.mdx @@ -17,11 +17,11 @@ Check out our [troubleshooting guide](https://docs.openwebui.com/troubleshooting ::: -:::danger - -Right now, you can only configure one OAUTH provider at a time. -You cannot have Microsoft **and** Google as providers simultaneously. +:::danger Only One OIDC Provider Supported +Right now, you can only configure **one** OpenID Connect (OIDC) provider at a time via `OPENID_PROVIDER_URL`. +You cannot have Microsoft **and** Google as OIDC providers simultaneously. +*However, there is a community workaround for using both! See our [Dual OAuth Tutorial](/tutorials/tips/dual-oauth-configuration) for more details.* ::: ## OAuth Configuration Overview @@ -131,6 +131,9 @@ The following environment variables are used: ::: +:::tip Community Workaround: Multi-Provider OAuth +If you need to support both Microsoft and Google simultaneously, check out our **[Dual OAuth Configuration Tutorial](/tutorials/tips/dual-oauth-configuration)**. +::: ### OAuth Role Management Any OAuth provider that can be configured to return roles in the access token can be used to manage roles in Open WebUI. diff --git a/docs/tutorials/tips/dual-oauth-configuration.mdx b/docs/tutorials/tips/dual-oauth-configuration.mdx new file mode 100644 index 000000000..9dd3e8caa --- /dev/null +++ b/docs/tutorials/tips/dual-oauth-configuration.mdx @@ -0,0 +1,64 @@ +--- +title: Dual OAuth Configuration (Microsoft & Google) +sidebar_label: Dual OAuth Configuration +sidebar_position: 100 +description: Learn how to configure both Microsoft and Google OAuth providers simultaneously in Open WebUI using an unofficial community workaround. +--- + +# 🔐 Dual OAuth Configuration (Microsoft & Google) + +:::caution Unofficial Workaround +This configuration is a community-contributed workaround and is **not officially supported** by the Open WebUI team. While it works in current versions, behavior may change in future updates. This tutorial serves as a demonstration for advanced users. +::: + +## Overview + +While Open WebUI officially supports only one **OpenID Connect (OIDC)** provider at a time via the `OPENID_PROVIDER_URL` variable, it is possible to support both **Microsoft** and **Google** simultaneously. + +The trick is to configure one provider (e.g., Microsoft) as the primary OIDC provider and the other (e.g., Google) as a standard OAuth provider by utilizing Open WebUI's built-in support for specific providers. + +## Prerequisites + +- Access to your Open WebUI environment variables (Docker or local). +- Client IDs and Secrets from both [Google Cloud Console](https://console.cloud.google.com/) and [Microsoft Azure/Entra ID](https://entra.microsoft.com/). +- `OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true` must be enabled to ensure users are mapped to the same account regardless of the provider used. + +## Configuration logic + +Open WebUI uses `OPENID_PROVIDER_URL` as a generic "catch-all" for OIDC. However, it also has native modules for Google and Microsoft. By leaving the `OPENID_PROVIDER_URL` for Microsoft and providing only the Client IDs for Google, the system can internalize both flows. + +## Environment Variables + +Add the following to your `docker-compose.yaml` or environment config: + +```bash +# Enable signup and account merging (CRITICAL) +ENABLE_OAUTH_SIGNUP=true +OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true + +# 1. Microsoft as the primary OIDC provider +# This uses the generic OIDC flow via the OPENID_PROVIDER_URL +MICROSOFT_CLIENT_ID=your_microsoft_client_id +MICROSOFT_CLIENT_SECRET=your_microsoft_client_secret +MICROSOFT_CLIENT_TENANT_ID=your_tenant_id +MICROSOFT_REDIRECT_URI=https://your-webui.com/oauth/microsoft/callback +OPENID_PROVIDER_URL=https://login.microsoftonline.com/your_tenant_id/v2.0/.well-known/openid-configuration + +# 2. Google as a secondary OAuth provider +# Note: Do NOT provide an OPENID_PROVIDER_URL for Google. +# The system will use its internal Google OAuth implementation. +GOOGLE_CLIENT_ID=your_google_client_id +GOOGLE_CLIENT_SECRET=your_google_client_secret +``` + +## Why This Works + +1. **Microsoft** is handled via the generic OIDC flow because `OPENID_PROVIDER_URL` is set to the Microsoft endpoint. +2. **Google** is handled via the dedicated internal Google OAuth module because the system detects `GOOGLE_CLIENT_ID` but sees that the global `OPENID_PROVIDER_URL` is already "claimed" by Microsoft or simply isn't needed for the built-in Google module. +3. **Account Merging**: Since both providers return the user's email, `OAUTH_MERGE_ACCOUNTS_BY_EMAIL=true` ensures the user logs into the same profile whether they click "Sign in with Google" or "Sign in with Microsoft." + +## Troubleshooting + +- **Redirect Mismatch**: Ensure your Redirect URIs in both consoles match your `WEBUI_URL`. +- **Merge Failures**: Double-check that `OAUTH_MERGE_ACCOUNTS_BY_EMAIL` is set to `true`. +- **Microsoft Logout**: Microsoft often requires the `OPENID_PROVIDER_URL` to handle the logout redirect correctly. If logout fails, ensure this URL is correct for your tenant. From a8efeadb8f135f5dac7f19dd8ebf412da1e4b52c Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:12:47 +0100 Subject: [PATCH 45/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 580a658ca..387d1e44f 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -3216,11 +3216,14 @@ If you use `perplexity`, this variable is not relevant to you. #### `WEB_LOADER_ENGINE` - Type: `str` -- Default: `safe_web` +- Default: `(empty)` - Description: Specifies the loader to use for retrieving and processing web content. - Options: - - `requests` - Uses the Requests module with enhanced error handling. - - `playwright` - Uses Playwright for more advanced web page rendering and interaction. + - `safe_web` (default) - Uses internal fetching with enhanced error handling. + - `playwright` - Uses Playwright for rendering pages with JavaScript support. + - `firecrawl` - Uses Firecrawl service. + - `tavily` - Uses Tavily service. + - `external` - Uses an external web loader API. - Persistence: This environment variable is a `PersistentConfig` variable. :::info @@ -3279,7 +3282,7 @@ Using a remote Playwright browser via `PLAYWRIGHT_WS_URL` can be beneficial for: :::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). +This **timeout only applies when `WEB_LOADER_ENGINE` is set to `safe_web`** or left empty (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). ::: From 720b1aec381301004573d6bd7be81af31b7604b0 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:14:47 +0100 Subject: [PATCH 46/66] Update starting-with-openai-compatible.mdx --- .../starting-with-openai-compatible.mdx | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx index 284cfd020..911ea36bc 100644 --- a/docs/getting-started/quick-start/starting-with-openai-compatible.mdx +++ b/docs/getting-started/quick-start/starting-with-openai-compatible.mdx @@ -69,6 +69,25 @@ If running Open WebUI in Docker and your model server on your host machine, use --- +## Required API Endpoints + +To ensure full compatibility with Open WebUI, your server should implement the following OpenAI-standard endpoints: + +| Endpoint | Method | Required? | Purpose | +| :--- | :--- | :--- | :--- | +| `/v1/models` | `GET` | **Yes** | Used for model discovery and selecting models in the UI. | +| `/v1/chat/completions` | `POST` | **Yes** | The core endpoint for chat, supporting streaming and parameters like temperature. | +| `/v1/embeddings` | `POST` | No | Required if you want to use this provider for RAG (Retrieval Augmented Generation). | +| `/v1/audio/speech` | `POST` | No | Required for Text-to-Speech (TTS) functionality. | +| `/v1/audio/transcriptions` | `POST` | No | Required for Speech-to-Text (STT/Whisper) functionality. | +| `/v1/images/generations` | `POST` | No | Required for Image Generation (DALL-E) functionality. | + +### Supported Parameters + +Open WebUI passes standard OpenAI parameters such as `temperature`, `top_p`, `max_tokens` (or `max_completion_tokens`), `stop`, `seed`, and `logit_bias`. It also supports **Tool Use** (Function Calling) if your model and server support the `tools` and `tool_choice` parameters. + +--- + ## Step 3: Start Chatting! Select your connected server’s model in the chat menu and get started! From 1578d308c8d93bf2a0a7ecef619c3f901f2d585b Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:24:44 +0100 Subject: [PATCH 47/66] fix some links --- docs/features/rbac/permissions.md | 2 +- docs/getting-started/advanced-topics/development.md | 2 +- .../advanced-topics/https-encryption.md | 6 +++--- .../quick-start/starting-with-functions.mdx | 10 +++++----- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/features/rbac/permissions.md b/docs/features/rbac/permissions.md index bc38f92e2..4bf0e0488 100644 --- a/docs/features/rbac/permissions.md +++ b/docs/features/rbac/permissions.md @@ -134,4 +134,4 @@ While the UI is the recommended way to manage permissions, initial defaults can * `ENABLE_WEB_SEARCH=True` * `USER_PERMISSIONS_CHAT_FILE_UPLOAD=True` -See the [Environment Configuration](../getting-started/env-configuration.mdx) guide for a complete list of valid variables. +See the [Environment Configuration](../../getting-started/env-configuration.mdx) guide for a complete list of valid variables. diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index 13e342e31..0660be154 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -289,7 +289,7 @@ If you find that **icons or other static assets are failing to load**, it is oft **Solution:** You need to configure the `CORS_ALLOW_ORIGIN` environment variable in your backend. -- Check the [Environment Configuration](../getting-started/env-configuration.mdx#cors-settings) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`). +- Check the [Environment Configuration](../env-configuration.mdx#cors-settings) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`). - In a development environment, you can often set this in your `backend/dev.sh` script or your `.env` file. ## Contributing to Open WebUI diff --git a/docs/getting-started/advanced-topics/https-encryption.md b/docs/getting-started/advanced-topics/https-encryption.md index b24a44c75..7937e9404 100644 --- a/docs/getting-started/advanced-topics/https-encryption.md +++ b/docs/getting-started/advanced-topics/https-encryption.md @@ -28,9 +28,9 @@ The best method depends on your infrastructure. ### 🏠 For Local/Docker Users If you are running Open WebUI with Docker, the standard approach is to use a **Reverse Proxy**. This sits in front of Open WebUI and handles the SSL encryption. -* **[Nginx](../../../tutorials/https/nginx.md)**: The industry standard. Highly configurable, great performance. -* **[Caddy](../../../tutorials/https/caddy.md)**: **Easiest option**. Automatically obtains and renews Let's Encrypt certificates with minimal config. -* **[HAProxy](../../../tutorials/https/haproxy.md)**: Robust choice for advanced load balancing needs. +* **[Nginx](../../tutorials/https/nginx.md)**: The industry standard. Highly configurable, great performance. +* **[Caddy](../../tutorials/https/caddy.md)**: **Easiest option**. Automatically obtains and renews Let's Encrypt certificates with minimal config. +* **[HAProxy](../../tutorials/https/haproxy.md)**: Robust choice for advanced load balancing needs. ### ☁️ For Cloud Deployments * **Cloud Load Balancers**: (AWS ALB, Google Cloud Load Balancing) often handle SSL termination natively. diff --git a/docs/getting-started/quick-start/starting-with-functions.mdx b/docs/getting-started/quick-start/starting-with-functions.mdx index a44aab175..6a1170a65 100644 --- a/docs/getting-started/quick-start/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/starting-with-functions.mdx @@ -102,11 +102,11 @@ Some functions need credentials (like Anthropic’s API key): Ready to build your own? Check out our detailed development guides: -* **[Functions Overview](../../../features/plugin/functions/index.mdx)**: Learn the basics of the Functions system. -* **[Pipes Guide](../../../features/plugin/functions/pipe.mdx)**: Create custom model providers and logic pipelines. -* **[Filters Guide](../../../features/plugin/functions/filter.mdx)**: Intercept and modify messages (Input/Output guards). -* **[Actions Guide](../../../features/plugin/functions/action.mdx)**: Add buttons/actions to messages. -* **[Tools Guide](../../../features/plugin/tools/index.mdx)**: Build tools for LLMs to use (RAG, APIs). +* **[Functions Overview](../../features/plugin/functions/index.mdx)**: Learn the basics of the Functions system. +* **[Pipes Guide](../../features/plugin/functions/pipe.mdx)**: Create custom model providers and logic pipelines. +* **[Filters Guide](../../features/plugin/functions/filter.mdx)**: Intercept and modify messages (Input/Output guards). +* **[Actions Guide](../../features/plugin/functions/action.mdx)**: Add buttons/actions to messages. +* **[Tools Guide](../../features/plugin/tools/index.mdx)**: Build tools for LLMs to use (RAG, APIs). * **[Community Registry](https://openwebui.com/search)**: Browse hundreds of community-made functions. From 7436bf7ffea9b45af679527ed1dc3b1a6af37fc4 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:25:05 +0100 Subject: [PATCH 48/66] Update starting-with-functions.mdx --- docs/getting-started/quick-start/starting-with-functions.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/getting-started/quick-start/starting-with-functions.mdx b/docs/getting-started/quick-start/starting-with-functions.mdx index 6a1170a65..1e5c464b9 100644 --- a/docs/getting-started/quick-start/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/starting-with-functions.mdx @@ -98,8 +98,6 @@ Some functions need credentials (like Anthropic’s API key): ### Next Steps & Learn More -### Next Steps & Learn More - Ready to build your own? Check out our detailed development guides: * **[Functions Overview](../../features/plugin/functions/index.mdx)**: Learn the basics of the Functions system. From 77acd2064f7715807e824585aa6347eecd19aa02 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:26:51 +0100 Subject: [PATCH 49/66] fix more links --- docs/features/plugin/development/reserved-args.mdx | 2 +- docs/features/rag/index.md | 2 +- .../integrations/backend-controlled-ui-compatible-flow.md | 2 +- docs/tutorials/integrations/continue-dev.md | 4 ++-- docs/tutorials/integrations/ipex_llm.md | 4 ++-- docs/tutorials/integrations/iterm2.md | 6 +++--- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/features/plugin/development/reserved-args.mdx b/docs/features/plugin/development/reserved-args.mdx index 1f389e7fa..738e774c7 100644 --- a/docs/features/plugin/development/reserved-args.mdx +++ b/docs/features/plugin/development/reserved-args.mdx @@ -301,7 +301,7 @@ Note that the same files dict can also be accessed via `__metadata__["files"]` ( ### `__request__` -An instance of `fastapi.Request`. You can read more in the [migration page](/docs/features/plugin/migration/index.mdx) or in [fastapi's documentation](https://fastapi.tiangolo.com/reference/request/). +An instance of `fastapi.Request`. You can read more in the [migration page](/features/plugin/migration/) or in [fastapi's documentation](https://fastapi.tiangolo.com/reference/request/). ### `__task__` diff --git a/docs/features/rag/index.md b/docs/features/rag/index.md index 9895c9def..96c9e051f 100644 --- a/docs/features/rag/index.md +++ b/docs/features/rag/index.md @@ -61,7 +61,7 @@ A variety of parsers extract content from local and remote documents. For more, ## Google Drive Integration -When paired with a Google Cloud project that has the Google Picker API and Google Drive API enabled, this feature allows users to directly access their Drive files from the chat interface and upload documents, slides, sheets and more and uploads them as context to your chat. Can be enabled `Admin Panel` > `Settings` > `Documents` menu. Must set [`GOOGLE_DRIVE_API_KEY and GOOGLE_DRIVE_CLIENT_ID`](https://github.com/open-webui/docs/blob/main/docs/getting-started/env-configuration.md) environment variables to use. +When paired with a Google Cloud project that has the Google Picker API and Google Drive API enabled, this feature allows users to directly access their Drive files from the chat interface and upload documents, slides, sheets and more and uploads them as context to your chat. Can be enabled `Admin Panel` > `Settings` > `Documents` menu. Must set [`GOOGLE_DRIVE_API_KEY and GOOGLE_DRIVE_CLIENT_ID`](../../getting-started/env-configuration.mdx) environment variables to use. ### Detailed Instructions diff --git a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md index fef44d2b6..054423e24 100644 --- a/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md +++ b/docs/tutorials/integrations/backend-controlled-ui-compatible-flow.md @@ -5,7 +5,7 @@ title: "Backend-Controlled, UI-Compatible API Flow" :::warning -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](/docs/tutorials/tips/contributing-tutorial.md). +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](/tutorials/tips/contributing-tutorial). ::: diff --git a/docs/tutorials/integrations/continue-dev.md b/docs/tutorials/integrations/continue-dev.md index bf52149a5..d4369af0b 100644 --- a/docs/tutorials/integrations/continue-dev.md +++ b/docs/tutorials/integrations/continue-dev.md @@ -5,7 +5,7 @@ title: "Continue.dev VS Code Extension with Open WebUI" :::warning -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](/docs/contributing.mdx). +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](/contributing). ::: @@ -153,7 +153,7 @@ env: This is a crucial step: you need to direct the continue.dev extension requests to your Open WebUI instance. Either use an actual domain name if the instance is hosted somewhere (e.g., `https://example.com/api`) or your localhost setup (e.g., `http://localhost:3000/api`). -You can find more information about the URLs in the [API Endpoints guide](/docs/getting-started/api-endpoints.md). +You can find more information about the URLs in the [API Endpoints guide](/getting-started/api-endpoints). ```yaml apiBase: http://localhost:3000/api diff --git a/docs/tutorials/integrations/ipex_llm.md b/docs/tutorials/integrations/ipex_llm.md index 36ce47dea..52e7a7a3d 100644 --- a/docs/tutorials/integrations/ipex_llm.md +++ b/docs/tutorials/integrations/ipex_llm.md @@ -5,13 +5,13 @@ title: "Local LLM Setup with IPEX-LLM on Intel GPU" :::warning -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. +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](/contributing). ::: :::note -This guide is verified with Open WebUI setup through [Manual Installation](docs/getting-started/index.md). +This guide is verified with Open WebUI setup through [Manual Installation](../../getting-started/index.md). ::: diff --git a/docs/tutorials/integrations/iterm2.md b/docs/tutorials/integrations/iterm2.md index b78cc41d8..55e94854e 100644 --- a/docs/tutorials/integrations/iterm2.md +++ b/docs/tutorials/integrations/iterm2.md @@ -4,7 +4,7 @@ title: "Iterm2 AI Integration" :::warning -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](/docs/contributing.mdx). +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](/contributing). ::: @@ -18,7 +18,7 @@ Whenever you forget a command or need a quick bash script for a repetitive task, ## Why connect to your Open WebUI instance? -Open WebUI provides a simple and straightforward way to interact with your LLMs via its [API Endpoints](/docs/getting-started/api-endpoints.md). This is particularly beneficial if you are running your own LLMs locally. Furthermore, you can leverage all your implemented features, monitoring, and other capabilities. +Open WebUI provides a simple and straightforward way to interact with your LLMs via its [API Endpoints](/getting-started/api-endpoints). This is particularly beneficial if you are running your own LLMs locally. Furthermore, you can leverage all your implemented features, monitoring, and other capabilities. ## Prerequisites @@ -92,7 +92,7 @@ Set your preferred amount of tokens here. Typically, your inference tool will al This is a crucial step: you need to direct the iTerm2 AI plugin requests to your Open WebUI instance. Either use an actual domain name if the instance is hosted somewhere (e.g., `https://example.com/api/chat/completions`) or your localhost setup (e.g., `http://localhost:8080/api/chat/completions`). -You can find more information about the URLs in the [API Endpoints guide](/docs/getting-started/api-endpoints.md). +You can find more information about the URLs in the [API Endpoints guide](/getting-started/api-endpoints). --- From f2fac4a0ffb8a8f1a5d6af7cc6da52a05ace209c Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:39:27 +0100 Subject: [PATCH 50/66] tooling descriptions --- docs/features/plugin/tools/index.mdx | 164 +++++++++++---------------- docusaurus.config.ts | 1 + 2 files changed, 69 insertions(+), 96 deletions(-) diff --git a/docs/features/plugin/tools/index.mdx b/docs/features/plugin/tools/index.mdx index a7db57ebe..18636359b 100644 --- a/docs/features/plugin/tools/index.mdx +++ b/docs/features/plugin/tools/index.mdx @@ -5,140 +5,112 @@ title: "Tools" # ⚙️ What are Tools? -Tools are small Python scripts that add superpowers to your LLM. When enabled, they allow your chatbot to do amazing things — like search the web, scrape data, generate images, talk back using AI voices, and more. +Tools are the various ways you can extend an LLM's capabilities beyond simple text generation. When enabled, they allow your chatbot to do amazing things — like search the web, scrape data, generate images, talk back using AI voices, and more. -Think of Tools as useful plugins that your AI can use when chatting with you. +Because there are several ways to integrate "Tools" in Open WebUI, it's important to understand which type you are using. --- -## 🚀 What Can Tools Help Me Do? +## 🧩 Tooling Taxonomy: Which "Tool" are you using? -Here are just a few examples of what Tools let your AI assistant do: +Users often encounter the term "Tools" in different contexts. Here is how to distinguish them: -- 🌍 Web Search: Get real-time answers by searching the internet. -- 🖼️ Image Generation: Create images from your prompts. -- 🔊 Voice Output: Generate AI voices using ElevenLabs. +| Type | Location in UI | Best For... | Source | +| :--- | :--- | :--- | :--- | +| **Native Features** | Admin/Settings | Core platform functionality | Built-in to Open WebUI | +| **Workspace Tools** | `Workspace > Tools` | User-created or community Python scripts | [Community Library](https://openwebui.com/search) | +| **Native MCP (HTTP)** | `Settings > Connections` | Standard MCP servers reachable via HTTP/SSE | External MCP Servers | +| **MCP via Proxy (MCPO)** | `Settings > Connections` | Local stdio-based MCP servers (e.g., Claude Desktop tools) | [MCPO Adapter](https://github.com/open-webui/mcpo) | +| **OpenAPI Servers** | `Settings > Connections` | Standard REST/OpenAPI web services | External Web APIs | -Explore ready-to-use tools in the 🧰 [Tools Showcase](https://openwebui.com/tools) +### 1. Native Features (Built-in) +These are deeply integrated into Open WebUI and generally don't require external scripts. +- **Web Search**: Integrated via engines like SearXNG, Google, or Tavily. +- **Image Generation**: Integrated with DALL-E, ComfyUI, or Automatic1111. +- **RAG (Knowledge)**: The ability to query uploaded documents (`#`). ---- - -## 📦 How to Install Tools - -There are two easy ways to install Tools in Open WebUI: - -1. Go to [Community Tool Library](https://openwebui.com/tools) -2. Choose a Tool, then click the Get button. -3. Enter your Open WebUI instance’s IP address or URL. -4. Click “Import to WebUI” — done! +### 2. Workspace Tools (Custom Plugins) +These are **Python scripts** that run directly within the Open WebUI environment. +- **Capability**: Can do anything Python can do (web scraping, complex math, API calls). +- **Access**: Managed via the `Workspace` menu. +- **Safety**: Always review code before importing, as these run on your server. +- **⚠️ Security Warning**: Normal or untrusted users should **not** be given permission to access the Workspace Tools section. This access allows a user to upload and execute arbitrary Python code on your server, which could lead to a full system compromise. -:::warning +### 3. MCP (Model Context Protocol) 🔌 +MCP is an open standard that allows LLMs to interact with external data and tools. +- **Native HTTP MCP**: Open WebUI can connect directly to any MCP server that exposes an HTTP/SSE endpoint. +- **MCPO (Proxy)**: Most community MCP servers use `stdio` (local command line). To use these in Open WebUI, you use the [**MCPO Proxy**](../../plugin/tools/openapi-servers/mcp.mdx) to bridge the connection. -Safety Tip: Never import a Tool you don’t recognize or trust. These are Python scripts and might run unsafe code. - -::: +### 4. OpenAPI / Function Calling Servers +Generic web servers that provide an OpenAPI (`.json` or `.yaml`) specification. Open WebUI can ingest these specs and treat every endpoint as a tool. --- -## 🔧 How to Use Tools in Open WebUI - -Once you've installed Tools (we’ll show you how below), here’s how to enable and use them: +## 📦 How to Install & Manage Workspace Tools -You have two ways to enable a Tool for your model: +Workspace Tools are the most common way to extend your instance with community features. -### ➕ Option 1: Enable from the Chat Window - -While chatting, click the ➕ icon in the input area. You’ll see a list of available Tools — you can enable any of them on the fly for that session. - -:::tip - -Tip: Enabling a Tool gives the model permission to use it — but it may not use it unless it's useful for the task. +1. Go to [Community Tool Library](https://openwebui.com/search) +2. Choose a Tool, then click the **Get** button. +3. Enter your Open WebUI instance’s URL (e.g. `http://localhost:3000`). +4. Click **Import to WebUI**. +:::warning Safety Tip +Never import a Tool you don’t recognize or trust. These are Python scripts and might run unsafe code on your host system. **Crucially, ensure you only grant "Tool" permissions to trusted users**, as the ability to create or import tools is equivalent to the ability to run arbitrary code on the server. ::: -### ✏️ Option 2: Enable by Default (Recommended for Frequent Use) -1. Go to: Workspace ➡️ Models -2. Choose the model you’re using (like GPT-4 or LLaMa2) and click the ✏️ edit icon. -3. Scroll down to the “Tools” section. -4. ✅ Check the Tools you want your model to have access to by default. -5. Click Save. +--- -This ensures the model always has these Tools ready to use whenever you chat with it. +## 🔧 How to Use Tools in Chat -You can also let your LLM auto-select the right Tools using the AutoTool Filter: +Once installed or connected, here’s how to enable them for your conversations: -🔗 [AutoTool Filter](https://openwebui.com/f/hub/autotool_filter/) +### Option 1: Enable on-the-fly (Specific Chat) +While chatting, click the **➕ (plus)** icon in the input area. You’ll see a list of available Tools — you can enable them specifically for that session. -🎯 Note: Even when using AutoTool, you still need to enable your Tools using Option 2. +### Option 2: Enable by Default (Global/Model Level) +1. Go to **Workspace ➡️ Models**. +2. Choose the model you’re using and click the ✏️ edit icon. +3. Scroll to the **Tools** section. +4. ✅ Check the Tools you want this model to always have access to by default. +5. Click **Save**. -✅ And that’s it — your LLM is now Tool-powered! You're ready to supercharge your chats with web search, image generation, voice output, and more. +You can also let your LLM auto-select the right Tools using the [**AutoTool Filter**](https://openwebui.com/f/hub/autotool_filter/). --- ## 🧠 Choosing How Tools Are Used: Default vs Native -Once Tools are enabled for your model, Open WebUI gives you two different ways to let your LLM use them in conversations. - -You can decide how the model should call Tools by choosing between: - -- 🟡 Default Mode (Prompt-based) -- 🟢 Native Mode (Built-in function calling) - -Let’s break it down: - -### 🟡 Default Mode (Prompt-based Tool Triggering) - -This is the default setting in Open WebUI. - -Here, your LLM doesn’t need to natively support function calling. Instead, we guide the model using smart tool selection prompt template to select and use a Tool. - -✅ Works with almost any model -✅ Great way to unlock Tools with basic or local models -❗ Not as reliable or flexible as Native Mode when chaining tools - -### 🟢 Native Mode (Function Calling Built-In) - -If your model does support “native” function calling (like GPT-4o or GPT-3.5-turbo-1106), you can use this powerful mode to let the LLM decide — in real time — when and how to call multiple Tools during a single chat message. - -✅ Fast, accurate, and can chain multiple Tools in one response -✅ The most natural and advanced experience -❗ Requires a model that actually supports native function calling - -### ✳️ How to Switch Between Modes - -Want to enable native function calling in your chats? Here's how: +Once Tools are enabled, Open WebUI gives you two different ways to let your LLM interact with them. You can switch this via the chat settings: ![Chat Controls](/images/features/plugin/tools/chat-controls.png) -1. Open the chat window with your model. -2. Click ⚙️ Chat Controls > Advanced Params. -3. Look for the Function Calling setting and switch it from Default → Native +1. Open a chat with your model. +2. Click ⚙️ **Chat Controls > Advanced Params**. +3. Look for the **Function Calling** setting and switch between: -That’s it! Your chat is now using true native Tool support (as long as the model supports it). +### 🟡 Default Mode (Prompt-based) +Here, your LLM doesn’t need to natively support function calling. We guide the model using a smart tool-selection prompt template to select and use a Tool. +- ✅ Works with **practically any model** (including smaller local models). +- 💡 **Admin Note**: You can also toggle the default mode for each specific model in the **Admin Panel > Settings > Models > Advanced Parameters**. -➡️ We recommend using GPT-4o or another OpenAI model for the best native function-calling experience. -🔎 Some local models may claim support, but often struggle with accurate or complex Tool usage. +- ❗ Not as reliable as Native Mode when chaining multiple complex tools. -💡 Summary: +### 🟢 Native Mode (Built-in Function Calling) +If your model supports native function calling (like GPT-4o, Gemini, Claude, or GPT-5), use this for a faster, more accurate experience where the LLM decides exactly when and how to call tools. +- ✅ Fast, accurate, and can chain multiple tools in one response. +- ❗ Requires a model that explicitly supports tool-calling schemas. | Mode | Who it’s for | Pros | Cons | |----------|----------------------------------|-----------------------------------------|--------------------------------------| -| Default | Any model | Broad compatibility, safer, flexible | May be less accurate or slower | -| Native | GPT-4o, etc. | Fast, smart, excellent tool chaining | Needs proper function call support | - -Choose the one that works best for your setup — and remember, you can always switch on the fly via Chat Controls. - -👏 And that's it — your LLM now knows how and when to use Tools, intelligently. +| **Default** | Practically any model (basic/local) | Broad compatibility, safer, flexible | May be less accurate or slower | +| **Native** | GPT-4o, Gemini, Claude, GPT-5, etc. | Fast, smart, excellent tool chaining | Needs proper function call support | --- -## 🧠 Summary - -Tools are add-ons that help your AI model do much more than just chat. From answering real-time questions to generating images or speaking out loud — Tools bring your AI to life. - -- Visit: [https://openwebui.com/tools](https://openwebui.com/tools) to discover new Tools. -- Install them manually or with one-click. -- Enable them per model from Workspace ➡️ Models. -- Use them in chat by clicking ➕ +## 🚀 Summary & Next Steps -Now go make your AI waaaaay smarter 🤖✨ +Tools bring your AI to life by giving it hands to interact with the world. +- **Browse Tools**: [openwebui.com/search](https://openwebui.com/search) +- **Advanced Setup**: Learn more about [MCP Support](./openapi-servers/mcp.mdx) +- **Development**: [Writing your own Custom Toolkits](./development.mdx) diff --git a/docusaurus.config.ts b/docusaurus.config.ts index b3f9ab0b6..6311bae82 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -54,6 +54,7 @@ const config: Config = { // blog: false, blog: { showReadingTime: true, + onUntruncatedBlogPosts: "ignore", // Please change this to your repo. // Remove this to remove the "edit this page" links. // editUrl: From a4aac29e19811e1126ba9f328831c7e1d06a98bd Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:46:29 +0100 Subject: [PATCH 51/66] broken links fixing. --- docs/features/plugin/functions/action.mdx | 4 ++-- docs/features/plugin/functions/index.mdx | 2 +- docs/features/web-search/tavily.md | 2 +- docs/getting-started/advanced-topics/development.md | 2 +- docs/getting-started/quick-start/starting-with-functions.mdx | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/features/plugin/functions/action.mdx b/docs/features/plugin/functions/action.mdx index 80577608e..a17d8ee6d 100644 --- a/docs/features/plugin/functions/action.mdx +++ b/docs/features/plugin/functions/action.mdx @@ -7,7 +7,7 @@ Action functions allow you to write custom buttons that appear in the message to Actions are admin-managed functions that extend the chat interface with custom interactive capabilities. When a message is generated by a model that has actions configured, these actions appear as clickable buttons beneath the message. -A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/). For more Action Function examples built by the community, visit [https://openwebui.com/functions](https://openwebui.com/functions). +A scaffold of Action code can be found [in the community section](https://openwebui.com/f/hub/custom_action/). For more Action Function examples built by the community, visit [https://openwebui.com/search](https://openwebui.com/search). An example of a graph visualization Action can be seen in the video below. @@ -313,4 +313,4 @@ Actions integrate seamlessly with other Open WebUI features: - **Memory** - Actions can access conversation history and context - **Permissions** - Actions respect user roles and access controls -For more examples and community-contributed actions, visit [https://openwebui.com/functions](https://openwebui.com/functions) where you can discover, download, and explore custom functions built by the Open WebUI community. +For more examples and community-contributed actions, visit [https://openwebui.com/search](https://openwebui.com/search) where you can discover, download, and explore custom functions built by the Open WebUI community. diff --git a/docs/features/plugin/functions/index.mdx b/docs/features/plugin/functions/index.mdx index 558bcfe7d..227d697cd 100644 --- a/docs/features/plugin/functions/index.mdx +++ b/docs/features/plugin/functions/index.mdx @@ -82,7 +82,7 @@ Learn how to set them up in the [**Action Functions Guide**](./action.mdx). Here's how to put Functions to work in Open WebUI: ### 1. **Install Functions** -You can install Functions via the Open WebUI interface or by importing them manually. You can find community-created functions on the [Open WebUI Community Site](https://openwebui.com/functions). +You can install Functions via the Open WebUI interface or by importing them manually. You can find community-created functions on the [Open WebUI Community Site](https://openwebui.com/search). ⚠️ **Be cautious.** Only install Functions from trusted sources. Running unknown code poses security risks. diff --git a/docs/features/web-search/tavily.md b/docs/features/web-search/tavily.md index 1589628db..5184290c2 100644 --- a/docs/features/web-search/tavily.md +++ b/docs/features/web-search/tavily.md @@ -75,7 +75,7 @@ Ensure you have: - **Quota Exceeded**: Check your Tavily plan at [Tavily Pricing](https://tavily.com/#pricing). - **Settings Not Saved**: Verify admin privileges and that `webui.db` is writable. -For further help, visit the [Open WebUI Community](https://openwebui.com/community) or [Tavily Support](https://tavily.com/#contact). +For further help, visit the [Open WebUI Community](https://openwebui.com/search) or [Tavily Support](https://tavily.com/#contact). ## Additional Resources diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index 0660be154..9883519f7 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -289,7 +289,7 @@ If you find that **icons or other static assets are failing to load**, it is oft **Solution:** You need to configure the `CORS_ALLOW_ORIGIN` environment variable in your backend. -- Check the [Environment Configuration](../env-configuration.mdx#cors-settings) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`). +- Check the [Environment Configuration](../env-configuration.mdx#cors_allow_origin) guide for details on how to set `CORS_ALLOW_ORIGIN` to allow requests from your frontend's URL (e.g., `http://localhost:5173`). - In a development environment, you can often set this in your `backend/dev.sh` script or your `.env` file. ## Contributing to Open WebUI diff --git a/docs/getting-started/quick-start/starting-with-functions.mdx b/docs/getting-started/quick-start/starting-with-functions.mdx index 1e5c464b9..a949e1dec 100644 --- a/docs/getting-started/quick-start/starting-with-functions.mdx +++ b/docs/getting-started/quick-start/starting-with-functions.mdx @@ -28,7 +28,7 @@ Functions are powerful tools, and the community has created thousands of them! Y To search and import functions directly from **[Open WebUI Community](https://openwebui.com/search)**, you must be logged in with a registered community account. ::: -1. Go to **[Open WebUI Community Search](https://openwebui.com/search)** (or browse `https://openwebui.com/functions`). +1. Go to **[Open WebUI Community Search](https://openwebui.com/search)**. 2. Explore the library! You can find functions for: * **New Providers**: Anthropic, Google Gemini, Groq. * **Tools**: Web Search, Calculator, Home Assistant control. From 9a0541d65eeef5e918f1aeee1010e5952b7fd0ed Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 21:52:06 +0100 Subject: [PATCH 52/66] docling --- .../rag/document-extraction/docling.md | 38 +++++++++++++++++++ docs/getting-started/env-configuration.mdx | 28 ++++++++------ 2 files changed, 54 insertions(+), 12 deletions(-) diff --git a/docs/features/rag/document-extraction/docling.md b/docs/features/rag/document-extraction/docling.md index 7184db371..e73234737 100644 --- a/docs/features/rag/document-extraction/docling.md +++ b/docs/features/rag/document-extraction/docling.md @@ -104,6 +104,44 @@ This command starts the Docling container and maps port 5001 from the container - You can try uploading some files via the UI and it should return output in MD format or your desired format +## Docling Parameters Reference + +When using Open WebUI with Docling version 2.0.0+, you can configure advanced processing options via the `DOCLING_PARAMS` JSON object in the **Admin Settings > Documents** or via the environment variable. + +### Common Parameters + +| Parameter | Type | Description | Allowed Values / Examples | +| :--- | :--- | :--- | :--- | +| `pdf_backend` | `string` | The PDF parsing engine to use. | `dlparse_v1`, `dlparse_v2`, `dlparse_v4`, `pypdfium2` | +| `table_mode` | `string` | Quality/speed tradeoff for tables. | `fast`, `accurate` | +| `ocr_engine` | `string` | The OCR library for scanned documents. | `tesseract`, `easyocr`, `ocrmac`, `rapidocr`, `tesserocr` | +| `do_ocr` | `bool` | Whether to perform OCR. | `true`, `false` | +| `force_ocr` | `bool` | Force OCR even on digital PDFs. | `true`, `false` | +| `pipeline` | `string` | Processing pipeline complexity. | `standard`, `fast` | +| `ocr_lang` | `list[string]` | Languages for OCR. | `["eng"]` (3-letter) for Tesseract; `["en"]` (2-letter) for EasyOCR | + +:::tip +**Language Codes**: The format of `ocr_lang` depends on the engine: +- **Tesseract / Tesserocr**: Uses 3-letter ISO 639-2 codes (e.g., `eng`, `deu`, `fra`, `spa`). +- **EasyOCR / RapidOCR**: Typically use 2-letter ISO 639-1 codes (e.g., `en`, `de`, `fr`, `es`). +::: + +:::tip +**dlparse** vs **dbparse**: Note that the backend names use **`dlparse`** (Deep Learning Parse), not `dbparse`. For modern Docling (v2+), `dlparse_v4` is generally recommended for the best balance of features. +::: + +### Example Configuration + +```json + { + "do_ocr": true, + "pdf_backend": "dlparse_v4", + "table_mode": "accurate", + "ocr_engine": "tesseract", + "ocr_lang": ["eng"] + } +``` + ### Conclusion Integrating Docling with Open WebUI is a simple and effective way to enhance document processing and content extraction capabilities. By following the steps in this guide, you can set up Docling as the default extraction engine and verify it’s working smoothly in a Docker environment. Once configured, Docling enables powerful, format-agnostic document parsing to support more advanced AI features in Open WebUI. diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 387d1e44f..a426bbe0b 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2224,18 +2224,18 @@ The old individual environment variables (`DOCLING_OCR_ENGINE`, `DOCLING_OCR_LAN - Description: Specifies all Docling processing parameters in JSON format. This is the primary configuration method for Docling processing options. All previously individual Docling settings are now configured through this single JSON object. **Supported Parameters:** - - `do_ocr` (bool): Enable OCR processing - - `force_ocr` (bool): Force OCR even when text layer exists - - `ocr_engine` (str): OCR engine to use (`tesseract`, `easyocr`, `ocrmac`, `rapidocr`, `tesserocr`) - - `ocr_lang` (list[str]): OCR language codes (e.g., `["en", "de", "fr"]`) - - `pdf_backend` (str): PDF processing backend - - `table_mode` (str): Table extraction mode - - `pipeline` (str): Processing pipeline to use - - `do_picture_description` (bool): Enable image description generation - - `picture_description_mode` (str): Mode for picture descriptions - - `picture_description_local` (str): Local model for picture descriptions - - `picture_description_api` (str): API endpoint for picture descriptions - - `vlm_pipeline_model_api` (str): Vision-language model API configuration + - `do_ocr` (bool): Enable OCR processing. + - `force_ocr` (bool): Force OCR even when text layer exists. + - `ocr_engine` (str): OCR engine to use. Options: `tesseract`, `easyocr`, `ocrmac`, `rapidocr`, `tesserocr`. + - `ocr_lang` (list[str]): OCR language codes. Note: Format depends on engine (e.g., `["eng", "fra"]` for Tesseract; `["en", "fr"]` for EasyOCR). + - `pdf_backend` (str): PDF processing backend. Options: `dlparse_v1`, `dlparse_v2`, `dlparse_v4`, `pypdfium2`. + - `table_mode` (str): Table extraction mode. Options: `fast`, `accurate`. + - `pipeline` (str): Processing pipeline to use. Options: `fast`, `standard`. + - `do_picture_description` (bool): Enable image description generation. + - `picture_description_mode` (str): Mode for picture descriptions. Options: `local`, `api`. + - `picture_description_local` (str): Local model configuration object for picture descriptions. + - `picture_description_api` (str): API endpoint configuration object for picture descriptions. + - `vlm_pipeline_model_api` (str): Vision-language model API configuration. (e.g., `openai://gpt-4o`). - Example: ```json @@ -2252,6 +2252,10 @@ The old individual environment variables (`DOCLING_OCR_ENGINE`, `DOCLING_OCR_LAN } ``` +:::tip +**dlparse** vs **dbparse**: Note that the backend names use **`dlparse`** (Deep Learning Parse), not `dbparse`. For modern Docling (v2+), `dlparse_v4` is generally recommended for the best balance of features. +::: + - Persistence: This environment variable is a `PersistentConfig` variable. :::info From eb4cef348275d268754c61c3ecca995e7ab11141 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 22:00:15 +0100 Subject: [PATCH 53/66] docker info --- docs/faq.mdx | 38 ++++++++++++++----- .../quick-start/tab-python/Conda.md | 7 ++++ .../quick-start/tab-python/Uv.md | 4 ++ .../quick-start/tab-python/Venv.md | 7 ++++ 4 files changed, 47 insertions(+), 9 deletions(-) diff --git a/docs/faq.mdx b/docs/faq.mdx index bc4b0bcab..dbc64a8d4 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -39,22 +39,42 @@ The same principles apply in harsh terrestrial settings, including submarines, p ### 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: +**A:** To update Open WebUI, you must first pull the latest image, then stop and remove the existing container, and finally start a new one. Simply pulling the image isn't enough because the running container is still based on the old version. -1. **Updating the Docker Image**: The command `docker pull ghcr.io/open-webui/open-webui:main` updates the Docker image but not the running container or its data. -2. **Persistent Data in Docker Volumes**: Docker volumes store data independently of container lifecycles, preserving your data (like chat histories) through updates. -3. **Applying the Update**: Ensure your update takes effect by removing the existing container (which doesn't delete the volume) and creating a new one with the updated image and existing volume attached. +**Follow these exact steps:** -This process updates the app while keeping your data safe. +1. **Pull the latest image:** + ```bash + docker pull ghcr.io/open-webui/open-webui:main + ``` +2. **Stop and Remove the current container:** + ```bash + docker stop open-webui + docker rm open-webui + ``` +3. **Start the new container with your data attached:** + ```bash + docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main + ``` + +*(Note: If your container or volume has a different name, adjust the commands accordingly.)* + +For a deeper dive into update methods (including automated updates like Watchtower), check our full **[Updating Guide](/getting-started/updating)**. ### 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: +**A:** In Docker, containers are meant to be "disposable." Your data is safe **only if you have a Volume configured**. + +:::danger Important: Data Persistence +If you ran your container *without* the `-v open-webui:/app/backend/data` flag (or a similar volume mount in Docker Compose), your data is stored **inside** the container. In that specific case, deleting the container **will result in permanent data loss**. + +Always ensure you follow our **[Quick Start Guide](/getting-started/quick-start)** correctly to set up persistent volumes from the beginning. +::: -- **Volumes Preserve Data**: Docker volumes are designed to persist data outside of container lifecycles. As long as your data is stored in a volume, it remains intact, regardless of what happens to the container. -- **Safe Update Process**: When updating Open WebUI, removing the old container and creating a new one with the updated image does not affect the data stored in volumes. The key is not to explicitly delete the volume with commands like `docker volume rm`. +When you use a Volume (typically named `open-webui` in our examples), your data stays safe even when the container is deleted. When you start a new container and mount that same volume, the new version of the app attaches to your old data automatically. -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. +**Default Data Path:** +On most Linux systems, your volume data is physically stored at: `/var/lib/docker/volumes/open-webui/_data`. ### Q: Should I use the distro-packaged Docker or the official Docker package? diff --git a/docs/getting-started/quick-start/tab-python/Conda.md b/docs/getting-started/quick-start/tab-python/Conda.md index 15b106bf6..a423a1431 100644 --- a/docs/getting-started/quick-start/tab-python/Conda.md +++ b/docs/getting-started/quick-start/tab-python/Conda.md @@ -24,3 +24,10 @@ ```bash open-webui serve ``` + +:::tip 'open-webui: command not found'? +If your terminal says the command doesn't exist: +1. Ensure your conda environment is **activated** (`conda activate open-webui`). +2. If you still get an error, try running it via Python directly: `python -m open_webui serve` +3. If you want to store your data in a specific place, use (Linux/Mac): `DATA_DIR=./data open-webui serve` or (Windows): `$env:DATA_DIR=".\data"; open-webui serve` +::: diff --git a/docs/getting-started/quick-start/tab-python/Uv.md b/docs/getting-started/quick-start/tab-python/Uv.md index 22e1c96c7..24ca39427 100644 --- a/docs/getting-started/quick-start/tab-python/Uv.md +++ b/docs/getting-started/quick-start/tab-python/Uv.md @@ -33,3 +33,7 @@ Once `uv` is installed, running Open WebUI is a breeze. Use the command below, e ```powershell $env:DATA_DIR="C:\open-webui\data"; uvx --python 3.11 open-webui@latest serve ``` + +:::tip Why set DATA_DIR? +Setting `DATA_DIR` ensures your chats and settings are saved in a predictable location. If you don't set it, `uvx` might store it in a temporary folder that gets deleted when the process ends. +::: diff --git a/docs/getting-started/quick-start/tab-python/Venv.md b/docs/getting-started/quick-start/tab-python/Venv.md index 8d92f5f08..130727be5 100644 --- a/docs/getting-started/quick-start/tab-python/Venv.md +++ b/docs/getting-started/quick-start/tab-python/Venv.md @@ -36,3 +36,10 @@ Create isolated Python environments using `venv`. ```bash open-webui serve ``` + +:::tip 'open-webui: command not found'? +If your terminal says the command doesn't exist: +1. Ensure your virtual environment is **activated** (Step 2). +2. If you still get an error, try running it via Python directly: `python -m open_webui serve` +3. If you want to store your data in a specific place, use: `DATA_DIR=./data open-webui serve` +::: From 799780f877836f84342d64863f43b3c62fb71f83 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sat, 20 Dec 2025 22:40:47 +0100 Subject: [PATCH 54/66] filters --- docs/features/plugin/functions/filter.mdx | 315 +++++++++++++++++++++- 1 file changed, 312 insertions(+), 3 deletions(-) diff --git a/docs/features/plugin/functions/filter.mdx b/docs/features/plugin/functions/filter.mdx index 95e68e5a7..2f91efc1a 100644 --- a/docs/features/plugin/functions/filter.mdx +++ b/docs/features/plugin/functions/filter.mdx @@ -106,9 +106,9 @@ class Filter: ``` #### 🖼️ What’s happening? -- **toggle = True** creates a switch UI in Open WebUI—users can manually enable or disable the filter in real time. -- **icon** (with a Data URI) will show up as a little image next to the filter’s name. You can use any SVG as long as it’s Data URI encoded! -- **The `inlet` function** uses the `__event_emitter__` special argument to broadcast feedback/status to the UI, such as a little toast/notification that reads "Toggled!" +- **toggle = True** creates a switch UI in Open WebUI—users can manually enable or disable the filter in real time. +- **icon** (with a Data URI) will show up as a little image next to the filter’s name. You can use any SVG as long as it’s Data URI encoded! +- **The `inlet` function** uses the `__event_emitter__` special argument to broadcast feedback/status to the UI, such as a little toast/notification that reads "Toggled!" ![Toggle Filter](/images/features/plugin/functions/toggle-filter.png) @@ -116,6 +116,315 @@ You can use these mechanisms to make your filters dynamic, interactive, and visu --- +## ⚙️ Filter Administration & Configuration + +### 🌐 Global Filters vs. Model-Specific Filters + +Open WebUI provides a flexible multi-level filter system that allows you to control which filters are active, how they're enabled, and who can toggle them. Understanding this system is crucial for effective filter management. + +#### Filter Activation States + +Filters can exist in one of four states, controlled by two boolean flags in the database: + +| State | `is_active` | `is_global` | Effect | +|-------|------------|------------|--------| +| **Globally Enabled** | ✅ `True` | ✅ `True` | Applied to **ALL** models automatically, cannot be disabled per-model | +| **Globally Disabled** | ❌ `False` | `True` | Not applied anywhere - even though the filter is globally enabled, the filter itself is disabled | +| **Model-Specific** | ✅ `True` | ❌ `False` | Only applied to models where the admin explicitly enables it | +| **Inactive** | ❌ `False` | `False` | Not applied anywhere, even if filter is enabled for a model by the admin - the filter itself is turned off | + +:::tip Global Filter Behavior +When a filter is set as **Global** (`is_global=True`) and **Active** (`is_active=True`), it becomes **force-enabled** for all models: +- It appears in every model's filter list as **checked and greyed out** +- Admins **cannot** uncheck it in model settings +- It runs on **every** chat completion request, regardless of model +::: + +#### Admin Panel: Making a Filter Global + +**Location:** Admin Panel → Functions → Filter Management + +To make a filter global: +1. Navigate to the Admin Panel +2. Click on **Functions** in the sidebar +3. Find your filter in the list +4. Click the **three-dot menu (⋮)** next to the filter +5. Click the **🌐 Globe icon** to toggle `is_global` +6. Ensure the filter is also **Active** (green toggle switch) + +**API Endpoint:** +```http +POST /functions/id/{filter_id}/toggle/global +``` + +**Visual Indicators:** +- 🟢 Green toggle = `is_active=True` (filter is active) +- 🌐 Highlighted globe icon = `is_global=True` (applies to all models) + +--- + +### 🎛️ The Two-Tier Filter System + +Open WebUI uses a sophisticated two-tier system for managing filters on a per-model basis. This can be confusing at first, but it's designed to support both **always-on filters** and **user-toggleable filters**. + +#### Tier 1: FiltersSelector (Which filters are available?) + +**Location:** Model Settings → Filters → "Filters" Section + +This controls which filters are **available** for a specific model. + +**Behavior:** +- Shows **all** filters (both global and model-specific) +- **Global filters** appear as checked and disabled (can't be unchecked) +- **Regular filters** can be toggled on/off +- Saves to: `model.meta.filterIds` in the database + +**Example:** +```json +{ + "meta": { + "filterIds": ["filter-uuid-1", "filter-uuid-2"] + } +} +``` + +#### Tier 2: DefaultFiltersSelector (Which toggleable filters start enabled?) + +**Location:** Model Settings → Filters → "Default Filters" Section + +This section **only appears** when at least one toggleable filter is selected (or is global). + +**Purpose:** Controls which toggleable filters are **enabled by default** for new chats. + +**What is a "Toggleable" Filter?** + +A filter becomes toggleable when its Python code includes: +```python +class Filter: + def __init__(self): + self.toggle = True # This makes it toggleable! +``` + +**Behavior:** +- Only shows filters with `toggle=True` +- Only shows filters that are either: + - In `filterIds` (selected for this model), OR + - Have `is_global=true` (globally enabled) +- Controls whether the filter is **ON** or **OFF** by default in the chat UI +- Saves to: `model.meta.defaultFilterIds` + +**Example:** +```json +{ + "meta": { + "filterIds": ["filter-uuid-1", "filter-uuid-2", "filter-uuid-3"], + "defaultFilterIds": ["filter-uuid-2"] + } +} +``` + +**Interpretation:** +- All three filters are available for this model +- Only `filter-uuid-2` starts enabled by default +- If `filter-uuid-1` and `filter-uuid-3` have `toggle=True`, users can enable them manually in the chat UI + +--- + +### 🔄 Toggleable Filters vs. Always-On Filters + +Understanding the difference between these two types is key to using the filter system effectively. + +#### Always-On Filters (No `toggle` property) + +**Characteristics:** +- Run automatically whenever the filter is active for a model +- **No user control** in the chat interface +- Do **not** appear in the "Default Filters" section +- Do **not** show up in the chat integrations menu (⚙️ icon) + +**Use Cases:** +- Content moderation (always filter inappropriate content) +- PII scrubbing (always remove sensitive data) +- System-level transformations (always apply certain formatting) +- Security/compliance filters + +**Example:** +```python +class ContentModerationFilter: + def __init__(self): + # No toggle property - this is an always-on filter + pass + + def inlet(self, body: dict) -> dict: + # Always scrub PII before sending to model + last_message = body["messages"][-1]["content"] + body["messages"][-1]["content"] = self.scrub_pii(last_message) + return body +``` + +#### Toggleable Filters (`toggle=True`) + +**Characteristics:** +- Appear as **switches in the chat UI** (in the integrations menu - ⚙️ icon) +- Users can **enable/disable** them per chat session +- **Do** appear in the "Default Filters" section +- `defaultFilterIds` controls their initial state (ON or OFF) + +**Use Cases:** +- Web search integration (user decides when to search) +- Citation mode (user controls when to require sources) +- Verbose output mode (user toggles detailed responses) +- Translation filters (user enables when needed) +- Code formatting (user chooses when to apply) +- Thinking/reasoning toggle (user controls whether to show model reasoning) + +**Example:** +```python +class WebSearchFilter: + def __init__(self): + self.toggle = True # User can turn on/off + self.icon = "data:image/svg+xml;base64,..." # Shows in UI + + async def inlet(self, body: dict, __event_emitter__) -> dict: + # Only runs when user has enabled this filter + await __event_emitter__({ + "type": "status", + "data": {"description": "Searching the web...", "done": False} + }) + # ... perform web search ... + return body +``` + +**Where Toggleable Filters Appear:** + +1. **Model Settings → Default Filters Section** + - Configure which filters start enabled +2. **Chat UI → Integrations Menu (⚙️ icon)** + - Users can toggle filters on/off per chat + - Shows custom icons if provided + - Realtime enable/disable + +--- + +### 📊 Filter Execution Flow + +Here's the complete flow from admin configuration to filter execution: + +**1. ADMIN PANEL (Filter Creation & Global Settings)** +- Admin Panel → Functions → Create New Function +- Set type="filter" +- Toggle is_active (enable/disable filter globally) +- Toggle is_global (apply to all models) + +**2. MODEL CONFIGURATION (Per-Model Filter Selection)** +- Model Settings → Filters Section +- FiltersSelector: Select which filters for this model +- DefaultFiltersSelector: Set default enabled state (only for toggleable filters) + +**3. CHAT UI (User Interaction - Toggleable Filters Only)** +- Chat → Integrations Menu (⚙️) → Toggle Filters +- Users can enable/disable toggleable filters +- Always-on filters run automatically (no UI control) + +**4. REQUEST PROCESSING (Filter Compilation)** +- Backend: get_sorted_filter_ids() +- Fetch global filters (is_global=True, is_active=True) +- Add model-specific filters from model.meta.filterIds +- Filter by is_active status +- For toggleable filters: Check user's enabled state +- Sort by priority (from valves) + +**5. FILTER EXECUTION** +- Execute inlet() filters (pre-request) +- Send modified request to LLM +- Execute stream() filters (during streaming) +- Execute outlet() filters (post-response) + +--- + +### 🎨 UI Indicators & Visual Feedback + +#### In the Admin Functions Panel + +| Indicator | Meaning | +|-----------|---------| +| 🟢 Green toggle | Filter is active (`is_active=True`) | +| ⚪ Grey toggle | Filter is inactive (`is_active=False`) | +| 🌐 Highlighted globe | Filter is global (`is_global=True`) | +| 🌐 Unhighlighted globe | Filter is not global (`is_global=False`) | + +#### In Model Settings (FiltersSelector) + +| State | Checkbox | Description | +|-------|----------|-------------| +| Global Filter | ✅ Checked & Disabled (greyed) | "This filter is globally enabled" | +| Selected Filter | ✅ Checked & Enabled | "This filter is selected for this model" | +| Unselected Filter | ☐ Unchecked & Enabled | "Click to include this filter" | + +#### In Chat UI (Integrations Menu) + +| Element | Description | +|---------|-------------| +| Filter name | Shows the filter's display name | +| Custom icon | SVG icon from `self.icon` (if provided) | +| Toggle switch | Enable/disable the filter for this chat | +| Status badge | Shows if filter is currently active | + +--- + +### 💡 Best Practices for Filter Configuration + +#### 1. When to Use Global Filters + +✅ **Use global filters for:** +- Security and compliance (PII scrubbing, content moderation) +- System-wide formatting (standardize all outputs) +- Logging and analytics (track all requests) +- Organization-wide policies (enforce company guidelines) + +❌ **Don't use global filters for:** +- Optional features (use toggleable filters instead) +- Model-specific behavior (use model-specific filters) +- User-preference features (let users control via toggles) + +#### 2. When to Use Toggleable Filters + +✅ **Make a filter toggleable (`toggle=True`) when:** +- Users should control when it's active (web search, translation) +- It's an optional enhancement (citation mode, verbose output) +- It adds functionality users may not always want (code formatting) +- It has a performance cost that should be optional + +❌ **Don't make a filter toggleable when:** +- It's required for security/compliance (always-on is better) +- Users shouldn't be able to disable it (use always-on) +- It's a system-level transformation (global is better) + +#### 3. Organizing Filters for Your Organization + +**Recommended Structure:** + +``` +Global Always-On Filters: +├─ PII Scrubber (security) +├─ Content Moderator (compliance) +└─ Request Logger (analytics) + +Model-Specific Always-On Filters: +├─ Code Formatter (for coding models only) +├─ Medical Terminology Corrector (for medical models) +└─ Legal Citation Validator (for legal models) + +Toggleable Filters (User Choice): +├─ Web Search Integration +├─ Citation Mode +├─ Translation Filter +├─ Verbose Output Mode +└─ Image Description Generator +``` + +--- + ### 🎯 Key Components Explained #### 1️⃣ **`Valves` Class (Optional Settings)** From 17a9e0e1cf2e2c8d6d152e16ff1265aa4559b1fd Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 11:36:45 +0100 Subject: [PATCH 55/66] temporary chat information on document processing --- docs/features/chat-features/url-params.md | 1 + docs/features/index.mdx | 2 +- docs/features/rag/document-extraction/index.md | 4 ++++ docs/features/rag/index.md | 4 ++++ docs/features/rbac/permissions.md | 2 +- docs/getting-started/env-configuration.mdx | 2 +- docs/tutorials/integrations/firefox-sidebar.md | 1 + 7 files changed, 13 insertions(+), 3 deletions(-) diff --git a/docs/features/chat-features/url-params.md b/docs/features/chat-features/url-params.md index ab4195391..50140d6a0 100644 --- a/docs/features/chat-features/url-params.md +++ b/docs/features/chat-features/url-params.md @@ -79,6 +79,7 @@ The following table lists the available URL parameters, their function, and exam - **How to Set**: Set this parameter to `true` for a temporary chat session. - **Example**: `/?temporary-chat=true` - **Behavior**: This initiates a disposable chat session without saving history or applying advanced configurations. + - **Note**: Document processing in temporary chats is frontend-only for privacy. Complex files requiring backend parsing (e.g., DOCX) may not be fully supported. ### 9. **Code Interpreter** diff --git a/docs/features/index.mdx b/docs/features/index.mdx index 173b1ca97..6eba78e7e 100644 --- a/docs/features/index.mdx +++ b/docs/features/index.mdx @@ -202,7 +202,7 @@ import { TopBanners } from "@site/src/components/TopBanners"; - ✅ **Multiple Instances of Same Model in Chats**: Enhanced many model chat to support adding multiple instances of the same model. -- 💬 **Temporary Chat Feature**: Introduced a temporary chat feature, deprecating the old chat history setting to enhance user interaction flexibility. +- 💬 **Temporary Chat Feature**: Introduced a temporary chat feature, deprecating the old chat history setting to enhance user interaction flexibility. Please note that **document processing in temporary chats is performed entirely in the browser** to ensure privacy and data minimization. This means specific file types requiring backend processing (like complex DOCX parsing) may have limited functionality in temporary mode. - 🖋️ **User Message Editing**: Enhanced the user chat editing feature to allow saving changes without sending. diff --git a/docs/features/rag/document-extraction/index.md b/docs/features/rag/document-extraction/index.md index d9f3473d6..edbf53ab4 100644 --- a/docs/features/rag/document-extraction/index.md +++ b/docs/features/rag/document-extraction/index.md @@ -23,6 +23,10 @@ With proper document extraction, Open WebUI can help you: - Extract data in structured formats for further processing - Support multilingual content recognition +:::note Privacy in Temporary Chats +In **Temporary Chat** mode, document extraction is performed **exclusively in the browser** to prevent data from being stored or processed on the backend. This strict privacy measure means that some complex file formats (like certain DOCX files) that rely on backend parsers may not be processed correctly. +::: + ## Available Extraction Methods Open WebUI supports multiple document extraction engines to accommodate different needs and document types. Each extraction method has its own strengths and is suitable for different scenarios. diff --git a/docs/features/rag/index.md b/docs/features/rag/index.md index 96c9e051f..e3e838e6f 100644 --- a/docs/features/rag/index.md +++ b/docs/features/rag/index.md @@ -59,6 +59,10 @@ The dedicated RAG pipeline for summarizing YouTube videos via video URLs enables A variety of parsers extract content from local and remote documents. For more, see the [`get_loader`](https://github.com/open-webui/open-webui/blob/2fa94956f4e500bf5c42263124c758d8613ee05e/backend/apps/rag/main.py#L328) function. +:::warning Temporary Chat Limitations +When using **Temporary Chat**, document processing is restricted to **frontend-only** operations to ensure your data stays private and is not stored on the server. Consequently, advanced backend parsing (used for formats like complex DOCX files) is disabled, which may result in raw data being seen instead of parsed text. For full document support, use a standard chat session. +::: + ## Google Drive Integration When paired with a Google Cloud project that has the Google Picker API and Google Drive API enabled, this feature allows users to directly access their Drive files from the chat interface and upload documents, slides, sheets and more and uploads them as context to your chat. Can be enabled `Admin Panel` > `Settings` > `Documents` menu. Must set [`GOOGLE_DRIVE_API_KEY and GOOGLE_DRIVE_CLIENT_ID`](../../getting-started/env-configuration.mdx) environment variables to use. diff --git a/docs/features/rbac/permissions.md b/docs/features/rbac/permissions.md index 4bf0e0488..b2204a98c 100644 --- a/docs/features/rbac/permissions.md +++ b/docs/features/rbac/permissions.md @@ -85,7 +85,7 @@ Controls the features available to the user inside the chat interface. | **Text-to-Speech (TTS)**| Ability to use voice output. | | **Audio Call** | Ability to use the real-time audio call feature. | | **Multiple Models** | Ability to select multiple models for a simultaneous response. | -| **Temporary Chat** | **(Parent)** Ability to toggle "Temporary Chat" (incognito mode/history off). | +| **Temporary Chat** | **(Parent)** Ability to toggle "Temporary Chat" (incognito mode/history off). **Note:** Backend document parsing is disabled in this mode for privacy. | | **Enforced Temporary** | *(Requires Temporary Chat)* **Restricts** the user to *always* use temporary chat (history disabled). | ### 4. Features Permissions diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index a426bbe0b..2f9e8da1d 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -4622,7 +4622,7 @@ This is useful when you need a JWT access token for downstream validation or whe - Type: `bool` - Default: `True` -- Description: Enables or disables user permission to create temporary chats. +- Description: Enables or disables user permission to create temporary chats. **Note:** Temporary chats disable backend document parsing for privacy. - Persistence: This environment variable is a `PersistentConfig` variable. #### `USER_PERMISSIONS_CHAT_TEMPORARY_ENFORCED` diff --git a/docs/tutorials/integrations/firefox-sidebar.md b/docs/tutorials/integrations/firefox-sidebar.md index a222d6d0c..882a38a0b 100644 --- a/docs/tutorials/integrations/firefox-sidebar.md +++ b/docs/tutorials/integrations/firefox-sidebar.md @@ -82,6 +82,7 @@ The following URL parameters can be used to customize your Open WebUI instance: ### Temporary Chat Sessions - `temporary-chat`: Mark the chat as a temporary session by setting this parameter to `true` (e.g., `/?temporary-chat=true`) + - *Note: Document processing is frontend-only in temporary chats. Complex files requiring backend parsing may not work.* See https://docs.openwebui.com/features/chat-features/url-params for more info on URL parameters and how to use them. From 30be41ca49e53a63876dd0475f972fc9b162923d Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 11:40:51 +0100 Subject: [PATCH 56/66] warning on multi concurrency setups when updating --- docs/getting-started/env-configuration.mdx | 10 ++++++++++ .../quick-start/tab-docker/DockerUpdating.md | 9 +++++++++ .../getting-started/quick-start/tab-kubernetes/Helm.md | 10 ++++++++++ .../quick-start/tab-python/PythonUpdating.md | 10 ++++++++++ docs/getting-started/updating.mdx | 2 ++ 5 files changed, 41 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 2f9e8da1d..808730a74 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5437,6 +5437,16 @@ If you use UVICORN_WORKERS, you also need to ensure that related environment var ::: +:::warning Database Migrations with Multiple Workers +When `UVICORN_WORKERS > 1`, starting the application can trigger concurrent database migrations from multiple worker processes, potentially causing database schema corruption or inconsistent states. + +**Recommendation:** +After pulling a new image or installing an update, **always run Open WebUI with a single worker (`UVICORN_WORKERS=1`) first**. This ensures the database migration completes successfully in a single process. Once the migration is finished and the application has started, you can then restart it with your desired number of workers. + +**For Kubernetes, Helm, Minikube, and other orchestrated setups:** +Ensure that your deployment strategy allows for a single-replica or single-worker init container/job to handle migrations before scaling up to multiple replicas or workers. This is critical to prevent race conditions during schema updates. +::: + ### Cache Settings #### `CACHE_CONTROL` diff --git a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md index f5aacce8c..21c679e5a 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerUpdating.md +++ b/docs/getting-started/quick-start/tab-docker/DockerUpdating.md @@ -8,6 +8,15 @@ To update your local Docker installation to the latest version, you can either u The original `containrrr/watchtower` is **no longer maintained** and may fail with newer Docker versions. We recommend using the `nickfedor/watchtower` fork. ::: +:::warning Multi-Worker Environments +If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption. + +**Steps for proper update:** +1. Update and start your container with `UVICORN_WORKERS=1`. +2. Wait for the application to fully start and complete migrations. +3. Stop and restart the container with your desired number of workers. +::: + With [Watchtower](https://github.com/nickfedor/watchtower), you can automate the update process: ```bash diff --git a/docs/getting-started/quick-start/tab-kubernetes/Helm.md b/docs/getting-started/quick-start/tab-kubernetes/Helm.md index 7ea4e300e..44e064ed7 100644 --- a/docs/getting-started/quick-start/tab-kubernetes/Helm.md +++ b/docs/getting-started/quick-start/tab-kubernetes/Helm.md @@ -36,6 +36,16 @@ There are some [environment variables](https://docs.openwebui.com/getting-starte ::: +:::danger Critical for Updates +If you run Open WebUI with multiple replicas/pods (`replicaCount > 1`) or `UVICORN_WORKERS > 1`, you **MUST** scale down to a single replica/pod during updates. +1. Scale down deployment to 1 replica. +2. Apply the update (new image version). +3. Wait for the pod to be fully ready (database migrations complete). +4. Scale back up to your desired replica count. + +**Failure to do this can result in database corruption due to concurrent migrations.** +::: + ## Access the WebUI Set up port forwarding or load balancing to access Open WebUI from outside the cluster. diff --git a/docs/getting-started/quick-start/tab-python/PythonUpdating.md b/docs/getting-started/quick-start/tab-python/PythonUpdating.md index 39b0f5cbb..9f7c7e1d1 100644 --- a/docs/getting-started/quick-start/tab-python/PythonUpdating.md +++ b/docs/getting-started/quick-start/tab-python/PythonUpdating.md @@ -9,3 +9,13 @@ pip install -U open-webui The `-U` (or `--upgrade`) flag ensures that `pip` upgrades the package to the latest available version. That's it! Your **Open-WebUI** package is now updated and ready to use. + +:::warning Multi-Worker Environments +If you run Open WebUI with `UVICORN_WORKERS > 1` (e.g., in a production environment), you **MUST** ensure the update migration runs on a single worker first to prevent database schema corruption. + +**Steps for proper update:** +1. Update `open-webui` using `pip`. +2. Start the application with `UVICORN_WORKERS=1` environment variable set. +3. Wait for the application to fully start and complete migrations. +4. Stop and restart the application with your desired number of workers. +::: diff --git a/docs/getting-started/updating.mdx b/docs/getting-started/updating.mdx index 134862f03..8e375be1e 100644 --- a/docs/getting-started/updating.mdx +++ b/docs/getting-started/updating.mdx @@ -14,6 +14,8 @@ Keeping Open WebUI updated ensures you have the latest features, security patche - **Backup your data** before major version updates - **Check release notes** at https://github.com/open-webui/open-webui/releases for breaking changes - **Clear browser cache** after updating to ensure the latest web interface loads +- **Running Multiple Workers?** If you use `UVICORN_WORKERS > 1`, you **MUST** run the updated container with `UVICORN_WORKERS=1` first to perform database migrations safely. Once started successfully, you can restart with multiple workers. +::: ::: ## Manual Update From cdf1e469ed98c4fddb9a520a96a08c2f6615de63 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 13:29:02 +0100 Subject: [PATCH 57/66] docs for web search concurrent requests --- docs/features/web-search/bing.md | 6 ++++++ docs/features/web-search/brave.md | 8 +++++++- docs/features/web-search/ddgs.mdx | 6 ++++++ docs/features/web-search/exa.md | 6 ++++++ docs/features/web-search/external.md | 6 ++++++ docs/features/web-search/google-pse.md | 6 ++++++ docs/features/web-search/jina.md | 6 ++++++ docs/features/web-search/kagi.md | 6 ++++++ docs/features/web-search/mojeek.md | 10 ++++++++-- docs/features/web-search/ollama-cloud.mdx | 6 ++++++ docs/features/web-search/perplexity.mdx | 6 ++++++ docs/features/web-search/perplexity_search.mdx | 6 ++++++ docs/features/web-search/searchapi.md | 6 ++++++ docs/features/web-search/searxng.md | 6 ++++++ docs/features/web-search/serpapi.md | 6 ++++++ docs/features/web-search/serper.md | 6 ++++++ docs/features/web-search/serply.md | 6 ++++++ docs/features/web-search/serpstack.md | 6 ++++++ docs/features/web-search/tavily.md | 6 ++++++ docs/features/web-search/yacy.md | 6 ++++++ docs/getting-started/env-configuration.mdx | 9 ++++++++- 21 files changed, 131 insertions(+), 4 deletions(-) diff --git a/docs/features/web-search/bing.md b/docs/features/web-search/bing.md index db7559f66..39ee125dd 100644 --- a/docs/features/web-search/bing.md +++ b/docs/features/web-search/bing.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + :::warning Bing Search APIs will be retired on 11th August 2025. New deployments are not supported. diff --git a/docs/features/web-search/brave.md b/docs/features/web-search/brave.md index 567ae6ddc..e4a9deaa0 100644 --- a/docs/features/web-search/brave.md +++ b/docs/features/web-search/brave.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Brave API ### Docker Compose Setup @@ -23,5 +29,5 @@ services: RAG_WEB_SEARCH_ENGINE: "brave" BRAVE_SEARCH_API_KEY: "YOUR_API_KEY" RAG_WEB_SEARCH_RESULT_COUNT: 3 - RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10 + RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 1 ``` diff --git a/docs/features/web-search/ddgs.mdx b/docs/features/web-search/ddgs.mdx index 49968c8c5..9b58c1db7 100644 --- a/docs/features/web-search/ddgs.mdx +++ b/docs/features/web-search/ddgs.mdx @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## DDGS (Dux Distributed Global Search - previously DuckDuckGo) ### Setup diff --git a/docs/features/web-search/exa.md b/docs/features/web-search/exa.md index 1ea44bb15..b91ddb191 100644 --- a/docs/features/web-search/exa.md +++ b/docs/features/web-search/exa.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + # 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. diff --git a/docs/features/web-search/external.md b/docs/features/web-search/external.md index fb0453520..23a0776a3 100644 --- a/docs/features/web-search/external.md +++ b/docs/features/web-search/external.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## External Web Search API This option allows you to connect Open WebUI to your own self-hosted web search API endpoint. This is useful if you want to: diff --git a/docs/features/web-search/google-pse.md b/docs/features/web-search/google-pse.md index 9a019f5c9..656128e9c 100644 --- a/docs/features/web-search/google-pse.md +++ b/docs/features/web-search/google-pse.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Google PSE API ### Setup diff --git a/docs/features/web-search/jina.md b/docs/features/web-search/jina.md index 461f51424..a36d4545b 100644 --- a/docs/features/web-search/jina.md +++ b/docs/features/web-search/jina.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + # 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. diff --git a/docs/features/web-search/kagi.md b/docs/features/web-search/kagi.md index 15a932087..1829ee61c 100644 --- a/docs/features/web-search/kagi.md +++ b/docs/features/web-search/kagi.md @@ -8,3 +8,9 @@ title: "Kagi" 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. ::: + +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: diff --git a/docs/features/web-search/mojeek.md b/docs/features/web-search/mojeek.md index 1acd40ff8..79b332f92 100644 --- a/docs/features/web-search/mojeek.md +++ b/docs/features/web-search/mojeek.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Mojeek Search API ### Setup @@ -29,7 +35,7 @@ services: environment: ENABLE_RAG_WEB_SEARCH: True RAG_WEB_SEARCH_ENGINE: "mojeek" - BRAVE_SEARCH_API_KEY: "YOUR_MOJEEK_API_KEY" + MOJEEK_SEARCH_API_KEY: "YOUR_MOJEEK_API_KEY" RAG_WEB_SEARCH_RESULT_COUNT: 3 - RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 10 + RAG_WEB_SEARCH_CONCURRENT_REQUESTS: 1 ``` diff --git a/docs/features/web-search/ollama-cloud.mdx b/docs/features/web-search/ollama-cloud.mdx index 31ad052c1..0874daa81 100644 --- a/docs/features/web-search/ollama-cloud.mdx +++ b/docs/features/web-search/ollama-cloud.mdx @@ -8,3 +8,9 @@ title: "Ollama Cloud Web Search" 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. ::: + +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: diff --git a/docs/features/web-search/perplexity.mdx b/docs/features/web-search/perplexity.mdx index 34ade5023..5ab89c7a1 100644 --- a/docs/features/web-search/perplexity.mdx +++ b/docs/features/web-search/perplexity.mdx @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Perplexity API :::info diff --git a/docs/features/web-search/perplexity_search.mdx b/docs/features/web-search/perplexity_search.mdx index a347afda3..b6cec0c0e 100644 --- a/docs/features/web-search/perplexity_search.mdx +++ b/docs/features/web-search/perplexity_search.mdx @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Perplexity Search API :::info diff --git a/docs/features/web-search/searchapi.md b/docs/features/web-search/searchapi.md index f70c47f30..79b5a91f1 100644 --- a/docs/features/web-search/searchapi.md +++ b/docs/features/web-search/searchapi.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## SearchApi API [SearchApi](https://searchapi.io) is a collection of real-time SERP APIs. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `bing_news`, `google_scholar`, `google_patents`, and others. diff --git a/docs/features/web-search/searxng.md b/docs/features/web-search/searxng.md index 7de9c9874..1b49c7e53 100644 --- a/docs/features/web-search/searxng.md +++ b/docs/features/web-search/searxng.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + This guide provides instructions on how to set up web search capabilities in Open WebUI using SearXNG in Docker. ## SearXNG (Docker) diff --git a/docs/features/web-search/serpapi.md b/docs/features/web-search/serpapi.md index 85ffb6772..46d06a7cc 100644 --- a/docs/features/web-search/serpapi.md +++ b/docs/features/web-search/serpapi.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## SerpApi API [SerpApi](https://serpapi.com/) Scrape Google and other search engines from our fast, easy, and complete API. Any existing or upcoming SERP engine that returns `organic_results` is supported. The default web search engine is `google`, but it can be changed to `bing`, `baidu`, `google_news`, `google_scholar`, `google_patents`, and others. diff --git a/docs/features/web-search/serper.md b/docs/features/web-search/serper.md index f316f4442..6b2dd8c8e 100644 --- a/docs/features/web-search/serper.md +++ b/docs/features/web-search/serper.md @@ -8,3 +8,9 @@ title: "Serper" 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. ::: + +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: diff --git a/docs/features/web-search/serply.md b/docs/features/web-search/serply.md index 47d9e6524..9b11d3507 100644 --- a/docs/features/web-search/serply.md +++ b/docs/features/web-search/serply.md @@ -8,3 +8,9 @@ title: "Serply" 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. ::: + +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: diff --git a/docs/features/web-search/serpstack.md b/docs/features/web-search/serpstack.md index 5f4d861b6..85cebe7b3 100644 --- a/docs/features/web-search/serpstack.md +++ b/docs/features/web-search/serpstack.md @@ -8,3 +8,9 @@ title: "Serpstack" 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. ::: + +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: diff --git a/docs/features/web-search/tavily.md b/docs/features/web-search/tavily.md index 5184290c2..9838c93c0 100644 --- a/docs/features/web-search/tavily.md +++ b/docs/features/web-search/tavily.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Overview Integrating Tavily with Open WebUI allows your language model to perform real-time web searches, providing up-to-date and relevant information. This tutorial guides you through configuring Tavily as a web search provider in Open WebUI. diff --git a/docs/features/web-search/yacy.md b/docs/features/web-search/yacy.md index c55ddf6b8..1def81ca5 100644 --- a/docs/features/web-search/yacy.md +++ b/docs/features/web-search/yacy.md @@ -9,6 +9,12 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: +:::tip + +For a comprehensive list of all environment variables related to Web Search (including concurrency settings, result counts, and more), please refer to the [Environment Configuration documentation](../../getting-started/env-configuration#web-search). + +::: + ## Yacy API ### Setup diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 808730a74..e62468105 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -2897,6 +2897,13 @@ Allow only specific domains: WEB_FETCH_FILTER_LIST="example.com,trusted-site.org - Description: Maximum number of search results to crawl. - Persistence: This environment variable is a `PersistentConfig` variable. +#### `WEB_SEARCH_CONCURRENT_REQUESTS` + +- Type: `int` +- Default: `0` +- Description: Limits the number of concurrent search requests to the search engine provider. Set to `0` for unlimited concurrency (default). Set to `1` for sequential execution to prevent rate limiting errors (e.g., Brave Free Tier). +- Persistence: This environment variable is a `PersistentConfig` variable. + #### `WEB_LOADER_CONCURRENT_REQUESTS` - Type: `int` @@ -2906,7 +2913,7 @@ Allow only specific domains: WEB_FETCH_FILTER_LIST="example.com,trusted-site.org :::info -This environment variable was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". If you were using the old name, please update your configurations to use "WEB_LOADER_CONCURRENT_REQUESTS" as the old variable name is now deprecated and will not be recognized. This renaming clarifies its function, as it specifically controls the concurrency of the web *loader* component that fetches content from search results, not the initial search engine query itself. +"WEB_LOADER_CONCURRENT_REQUESTS" was previously named "WEB_SEARCH_CONCURRENT_REQUESTS". The variable "WEB_SEARCH_CONCURRENT_REQUESTS" has been repurposed to control the concurrency of the search engine requests (see above). To control the web *loader* concurrency (fetching content from results), you MUST use "WEB_LOADER_CONCURRENT_REQUESTS". ::: From de1586ea000679a5f0e638cac4f860b42b115919 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 15:08:01 +0100 Subject: [PATCH 58/66] force --- .../audio/text-to-speech/chatterbox-tts-api-integration.md | 4 ++++ docs/getting-started/advanced-topics/development.md | 3 +++ 2 files changed, 7 insertions(+) diff --git a/docs/features/audio/text-to-speech/chatterbox-tts-api-integration.md b/docs/features/audio/text-to-speech/chatterbox-tts-api-integration.md index 17990eb45..1b2c3c8d1 100644 --- a/docs/features/audio/text-to-speech/chatterbox-tts-api-integration.md +++ b/docs/features/audio/text-to-speech/chatterbox-tts-api-integration.md @@ -176,6 +176,8 @@ For local development, you can run the API and frontend separately: cd frontend && npm install && npm run dev ``` +> **Note:** If you encounter dependency issues, try running `npm install --force` instead of just `npm install`. + Click the link provided from Vite to access the web UI. ### Build for Production @@ -186,6 +188,8 @@ Build the frontend for production deployment: cd frontend && npm install && npm run build ``` +> **Note:** If the build fails due to dependency conflicts, try using `npm install --force`. + You can then access it directly from your local file system at `/dist/index.html`. ### Port Configuration diff --git a/docs/getting-started/advanced-topics/development.md b/docs/getting-started/advanced-topics/development.md index 9883519f7..53d6accbb 100644 --- a/docs/getting-started/advanced-topics/development.md +++ b/docs/getting-started/advanced-topics/development.md @@ -277,6 +277,9 @@ Hot reload (or hot module replacement - HMR) is a fantastic development feature ```bash rm -rf node_modules && npm install ``` + + If `npm install` fails, try `npm install --force`. + This command deletes the `node_modules` directory (where dependencies are stored) and then reinstalls them from scratch. This can resolve issues caused by corrupted or outdated packages. 5. **Backend Restart Required (For Backend Changes):** Hot reload typically works best for frontend code changes (UI, styling, components). For significant backend code changes (especially changes to server logic, API endpoints, or dependencies), you might need to **manually restart the backend server** (by stopping `sh dev.sh` in your backend terminal and running it again). Hot reload for backend changes is often less reliable or not automatically configured in many backend development setups. From a38902cd6473b958406af6d634e5f1dd08916d65 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 17:53:41 +0100 Subject: [PATCH 59/66] fallback behaviour --- docs/features/workspace/models.md | 1 + docs/getting-started/env-configuration.mdx | 6 ++++++ 2 files changed, 7 insertions(+) diff --git a/docs/features/workspace/models.md b/docs/features/workspace/models.md index add8249e8..d8ba3a4f2 100644 --- a/docs/features/workspace/models.md +++ b/docs/features/workspace/models.md @@ -25,6 +25,7 @@ Both actions lead to the same Model Builder interface, where you can configure t - **Avatar Photo**: Upload a custom image to represent your model in the chat interface. - **Model Name & ID**: The display name and unique identifier for your custom preset (e.g., "Python Tutor" or "Meeting Summarizer"). - **Base Model**: The actual model beneath the hood that powers the agent. You can choose *any* model connected to Open WebUI. You can create a custom preset for `gpt-4o` just as easily as `llama3`. + - **Fallback Behavior**: If the configured Base Model is unavailable and the `ENABLE_CUSTOM_MODEL_FALLBACK` environment variable is set to `True`, the system will automatically fall back to the first configured default model (set in Admin Panel > Settings > Models > Default Models). This ensures mission-critical custom models remain functional even if their specific base model is removed or temporarily unavailable. - **Description**: A short summary of what the model does. - **Tags**: Add tags to organize models in the selector dropdown. - **Visibility & Groups**: diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index e62468105..2b1e5588a 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -206,6 +206,12 @@ If you are running larger instances, you WILL NEED to set this to a higher value ::: +#### `ENABLE_CUSTOM_MODEL_FALLBACK` + +- Type: `bool` +- Default: `False` +- Description: Controls whether custom models should fall back to a default model if their assigned base model is missing. When set to `True`, if a custom model's base model is not found, the system will use the first model from the configured `DEFAULT_MODELS` list instead of returning an error. + #### `MODELS_CACHE_TTL` - Type: `int` From 63e78b9c3a56e9ddab47f079e9e1049af05842b6 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 18:43:27 +0100 Subject: [PATCH 60/66] notes --- docs/features/notes.md | 37 +++++++++++++++++++++++++++++++------ 1 file changed, 31 insertions(+), 6 deletions(-) diff --git a/docs/features/notes.md b/docs/features/notes.md index c8f60d314..da5293621 100644 --- a/docs/features/notes.md +++ b/docs/features/notes.md @@ -118,12 +118,6 @@ You can delete notes permanently from two locations: 1. **From the Notes Dashboard:** Click the **More (`...`)** button on the individual note card in the list view and select **Delete**. 2. **From the Editor:** While inside an open note, click the **More (`...`)** button in the top right corner of the screen and select **Delete**. -### Sharing Permissions - -Administrators can control whether users are allowed to share notes publicly: - -* **Environment Variable:** `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING` -* **Admin Panel:** Settings > Users > Default Permissions ### Quick Note Creation via URL @@ -134,6 +128,37 @@ Notes can be created directly by navigating to `/notes/new` with optional query This enables bookmarks and shortcuts for fast note creation. +### Creating Notes from Search + +You can also create notes directly from the global search bar: + +1. Open the search using the keyboard shortcut (`Cmd+K` / `Ctrl+K`) or by clicking the search icon. +2. Type your initial note content. +3. Select **"Create a new note"** from the actions list. +4. This will immediately open a new note with your search text as the content. + +### Importing Notes + +You can import existing Markdown (`.md`) files into your Notes workspace: + +* **Drag and Drop:** Simply drag `.md` files directly onto the Notes list view to import them. + +### View Options + +The Notes dashboard offers different ways to organize your content: + +* **Filter:** Toggle between **Created by you** (your private/shared notes) and **Shared with you** (notes others have shared). +* **Layout:** Switch between **List** and **Grid** views for visual preference. + +### Sharing Permissions + +Administrators can control sharing capabilities via environment variables or the Admin Panel: + +* **Internal Sharing:** `USER_PERMISSIONS_NOTES_ALLOW_SHARING` (Controls sharing with other users/groups on the server). +* **Public Sharing:** `USER_PERMISSIONS_NOTES_ALLOW_PUBLIC_SHARING` (Controls generating public external links). + +These can also be configured in **Admin Panel > Settings > Users > Default Permissions**. + --- ## Use Cases From 7bef04f2a9d22be80cb997f0b671e3c7f25a7b57 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 18:49:41 +0100 Subject: [PATCH 61/66] Update artifacts.md --- .../chat-features/code-execution/artifacts.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/features/chat-features/code-execution/artifacts.md b/docs/features/chat-features/code-execution/artifacts.md index 30f3080c2..ab2ebf411 100644 --- a/docs/features/chat-features/code-execution/artifacts.md +++ b/docs/features/chat-features/code-execution/artifacts.md @@ -100,3 +100,15 @@ Example Project: Develop a prototype for a new e-commerce website using HTML, CS - Benefits: Create interactive stories with scrolling effects, animations, and other interactive elements. Open WebUI's Artifacts enable you to refine the story and test different versions. Example Project: Build an interactive story about a company's history, using scrolling effects and animations to engage the reader. Use targeted updates to refine the story's narrative and Open WebUI's version selector to test different versions. + +## Troubleshooting + +### Artifacts Preview Not Working (Uncaught SecurityError) + +If you encounter an issue where the code preview in the chat interface does not appear and you see an error like `Artifacts.svelte:40 Uncaught SecurityError` in the browser console, this is commonly caused by cross-origin iframe restrictions in certain environment configurations. + +**Solution:** + +1. Go to **Settings > Interface**. +2. Toggle on **Allow Iframe Sandbox Same-Origin Access**. +3. Save your settings. From 4e81d47067764c71bc29e4a9cd28eb465888feaf Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 18:55:24 +0100 Subject: [PATCH 62/66] Update env-configuration.mdx --- docs/getting-started/env-configuration.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 2b1e5588a..a8097aeae 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -30,7 +30,9 @@ You can update the values of `PersistentConfig` environment variables directly f Please note that `PersistentConfig` environment variables are clearly marked as such in the documentation below, so you can be aware of how they will behave. -To disable `PersistentConfig` and have Open WebUI treat all variables equally, you can set `ENABLE_PERSISTENT_CONFIG` to `False`. +To disable this behavior and force Open WebUI to always use your environment variables (ignoring the database), set `ENABLE_PERSISTENT_CONFIG` to `False`. + +**CRITICAL WARNING:** When `ENABLE_PERSISTENT_CONFIG` is `False`, you may still be able to edit settings in the Admin UI. However, these changes are **NOT saved permanently**. They will persist only for the current session and will be **lost** when you restart the container, as the system will revert to the values defined in your environment variables. ::: @@ -259,7 +261,11 @@ This caches the external model lists retrieved from configured OpenAI-compatible - Type: `bool` - Default: `True` -- Description: If set to `False`, all `PersistentConfig` variables are treated as regular variables. +- Description: Controls whether the system prioritizes configuration saved in the database over environment variables. + - **`True` (Default):** Values saved in the **database** (via the Admin UI) take precedence. If a value is set in the UI, the environment variable is ignored for that setting. + - **`False`:** **Environment variables** take precedence. The system will *not* load configuration from the database at startup if an environment variable is present (or it will use the default). + - **CRITICAL WARNING:** When set to `False`, you can still seemingly "change" settings in the Admin UI. These changes will apply to the **current running session** but **will be lost upon restart**. The system will revert to the values defined in your environment variables (or defaults) every time it boots up. + - **Use Case:** Set this to `False` if you want to strictly manage configuration via a `docker-compose.yaml` or `.env` file and prevent UI changes from persisting across restarts. #### `CUSTOM_NAME` From 7a04bfd0e20aaec461c92a229ce758dba227ae8c Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 19:09:09 +0100 Subject: [PATCH 63/66] fix --- docs/features/interface/webhooks.md | 13 +++++++++ .../quick-start/tab-docker/DockerCompose.md | 27 ++++++++++++++++++- .../quick-start/tab-docker/ManualDocker.md | 20 ++++++++++++++ .../quick-start/tab-docker/Podman.md | 20 ++++++++++++++ .../quick-start/tab-kubernetes/Helm.md | 13 +++++++++ .../quick-start/tab-python/Conda.md | 13 +++++++++ .../quick-start/tab-python/Uv.md | 19 +++++++++++++ .../quick-start/tab-python/Venv.md | 14 ++++++++++ 8 files changed, 138 insertions(+), 1 deletion(-) diff --git a/docs/features/interface/webhooks.md b/docs/features/interface/webhooks.md index e6bc640d9..16b017f48 100644 --- a/docs/features/interface/webhooks.md +++ b/docs/features/interface/webhooks.md @@ -64,6 +64,19 @@ This webhook allows individual users to receive a notification when a model has 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. +### Enabling/Disabling User Webhooks + +User webhooks are enabled by default. However, administrators can disable this feature for all users to prevent external requests or for security reasons. + +This can be done in two ways: + +1. **Directly in the Admin Panel:** + - Go to **Admin Panel > Settings > General > Features**. + - Toggle the switch for **"User Webhooks"**. + +2. **Using Environment Variables:** + - Set the environment variable `ENABLE_USER_WEBHOOKS` to `False` in your backend configuration. This will globally disable the feature and hide the setting from user profiles. + ### Configuration 1. Click on your profile picture in the bottom-left corner to open the settings menu. diff --git a/docs/getting-started/quick-start/tab-docker/DockerCompose.md b/docs/getting-started/quick-start/tab-docker/DockerCompose.md index da1dbdc25..2e4b30efa 100644 --- a/docs/getting-started/quick-start/tab-docker/DockerCompose.md +++ b/docs/getting-started/quick-start/tab-docker/DockerCompose.md @@ -74,8 +74,33 @@ deploy: reservations: devices: - driver: nvidia - count: all + - count: all capabilities: [gpu] ``` This setup ensures that your application can leverage GPU resources when available. + +## Uninstall + +To uninstall Open WebUI running with Docker Compose, follow these steps: + +1. **Stop and Remove the Services:** + Run this command in the directory containing your `docker-compose.yml` file: + ```bash + docker compose down + ``` + +2. **Remove the Volume (Optional, WARNING: Deletes all data):** + If you want to completely remove your data (chats, settings, etc.): + ```bash + docker compose down -v + ``` + Or manually: + ```bash + docker volume rm _open-webui + ``` + +3. **Remove the Image (Optional):** + ```bash + docker rmi ghcr.io/open-webui/open-webui:main + ``` diff --git a/docs/getting-started/quick-start/tab-docker/ManualDocker.md b/docs/getting-started/quick-start/tab-docker/ManualDocker.md index bfd2c51ec..26370a85c 100644 --- a/docs/getting-started/quick-start/tab-docker/ManualDocker.md +++ b/docs/getting-started/quick-start/tab-docker/ManualDocker.md @@ -82,3 +82,23 @@ After the container is running, access Open WebUI at: [http://localhost:3000](http://localhost:3000) For detailed help on each Docker flag, see [Docker's documentation](https://docs.docker.com/engine/reference/commandline/run/). + +## Uninstall + +To uninstall Open WebUI running with Docker, follow these steps: + +1. **Stop and Remove the Container:** + ```bash + docker rm -f open-webui + ``` + +2. **Remove the Image (Optional):** + ```bash + docker rmi ghcr.io/open-webui/open-webui:main + ``` + +3. **Remove the Volume (Optional, WARNING: Deletes all data):** + If you want to completely remove your data (chats, settings, etc.): + ```bash + docker volume rm open-webui + ``` diff --git a/docs/getting-started/quick-start/tab-docker/Podman.md b/docs/getting-started/quick-start/tab-docker/Podman.md index 90f7edefd..58db332f9 100644 --- a/docs/getting-started/quick-start/tab-docker/Podman.md +++ b/docs/getting-started/quick-start/tab-docker/Podman.md @@ -48,3 +48,23 @@ Once inside Open WebUI, navigate to **Settings > Admin Settings > Connections** `http://host.containers.internal:11434` Refer to the Podman [documentation](https://podman.io/) for advanced configurations. + +## Uninstall + +To uninstall Open WebUI running with Podman, follow these steps: + +1. **Stop and Remove the Container:** + ```bash + podman rm -f openwebui + ``` + +2. **Remove the Image (Optional):** + ```bash + podman rmi ghcr.io/open-webui/open-webui:main + ``` + +3. **Remove the Volume (Optional, WARNING: Deletes all data):** + If you want to completely remove your data (chats, settings, etc.): + ```bash + podman volume rm open-webui + ``` diff --git a/docs/getting-started/quick-start/tab-kubernetes/Helm.md b/docs/getting-started/quick-start/tab-kubernetes/Helm.md index 44e064ed7..f0272cbd1 100644 --- a/docs/getting-started/quick-start/tab-kubernetes/Helm.md +++ b/docs/getting-started/quick-start/tab-kubernetes/Helm.md @@ -49,3 +49,16 @@ If you run Open WebUI with multiple replicas/pods (`replicaCount > 1`) or `UVICO ## Access the WebUI Set up port forwarding or load balancing to access Open WebUI from outside the cluster. + +## Uninstall + +1. **Uninstall the Helm Release:** + ```bash + helm uninstall openwebui + ``` + +2. **Remove Persistent Volume Claims (WARNING: Deletes all data):** + Helm does not automatically delete PVCs to prevent accidental data loss. You must delete them manually if you want to wipe everything. + ```bash + kubectl delete pvc -l app.kubernetes.io/instance=openwebui + ``` diff --git a/docs/getting-started/quick-start/tab-python/Conda.md b/docs/getting-started/quick-start/tab-python/Conda.md index a423a1431..df185cbc1 100644 --- a/docs/getting-started/quick-start/tab-python/Conda.md +++ b/docs/getting-started/quick-start/tab-python/Conda.md @@ -31,3 +31,16 @@ If your terminal says the command doesn't exist: 2. If you still get an error, try running it via Python directly: `python -m open_webui serve` 3. If you want to store your data in a specific place, use (Linux/Mac): `DATA_DIR=./data open-webui serve` or (Windows): `$env:DATA_DIR=".\data"; open-webui serve` ::: + +## Uninstall + +1. **Remove the Conda Environment:** + ```bash + conda remove --name open-webui --all + ``` + +2. **Remove Data (WARNING: Deletes all data):** + Delete your data directory (usually `~/.open-webui` unless configured otherwise): + ```bash + rm -rf ~/.open-webui + ``` diff --git a/docs/getting-started/quick-start/tab-python/Uv.md b/docs/getting-started/quick-start/tab-python/Uv.md index 24ca39427..bea48deb1 100644 --- a/docs/getting-started/quick-start/tab-python/Uv.md +++ b/docs/getting-started/quick-start/tab-python/Uv.md @@ -37,3 +37,22 @@ Once `uv` is installed, running Open WebUI is a breeze. Use the command below, e :::tip Why set DATA_DIR? Setting `DATA_DIR` ensures your chats and settings are saved in a predictable location. If you don't set it, `uvx` might store it in a temporary folder that gets deleted when the process ends. ::: + +## Uninstall + +To remove Open WebUI when running with `uvx`: + +1. **Stop the Server:** + Press `Ctrl+C` in the terminal where it's running. + +2. **Available cleanup commands:** + The `uvx` command runs the application ephemerally or from cache. To remove cached components: + ```bash + uv cache clean + ``` + +3. **Remove Data (WARNING: Deletes all data):** + Delete your data directory (default is `~/.open-webui` or the path set in `DATA_DIR`): + ```bash + rm -rf ~/.open-webui + ``` diff --git a/docs/getting-started/quick-start/tab-python/Venv.md b/docs/getting-started/quick-start/tab-python/Venv.md index 130727be5..5ad49bd6a 100644 --- a/docs/getting-started/quick-start/tab-python/Venv.md +++ b/docs/getting-started/quick-start/tab-python/Venv.md @@ -43,3 +43,17 @@ If your terminal says the command doesn't exist: 2. If you still get an error, try running it via Python directly: `python -m open_webui serve` 3. If you want to store your data in a specific place, use: `DATA_DIR=./data open-webui serve` ::: + +## Uninstall + +1. **Delete the Virtual Environment:** + Simply remove the `venv` folder: + ```bash + rm -rf venv + ``` + +2. **Remove Data (WARNING: Deletes all data):** + Delete your data directory (usually `~/.open-webui` unless configured otherwise): + ```bash + rm -rf ~/.open-webui + ``` From 9ea3a1282a35c48de38a37a6e3f8aa40f7b3eb4a Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 19:16:08 +0100 Subject: [PATCH 64/66] catch fix --- docs/getting-started/env-configuration.mdx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index a8097aeae..6c7744c4a 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -278,6 +278,7 @@ This caches the external model lists retrieved from configured OpenAI-compatible - Default: `Open WebUI` - Description: Sets the main WebUI name. Appends `(Open WebUI)` if overridden. + #### `PORT` - Type: `int` @@ -556,6 +557,7 @@ The AIOHTTP_CLIENT_TIMEOUT_MODEL_LIST is set to 10 seconds by default to help en - Default: `/chats,/chat,/folders` - Description: Comma-separated list of URL paths to exclude from audit logging. Paths are matched without leading slashes.RetryTo run code, enable code execution and file creation in Settings > Capabilities.Claude can make mistakes. Please double-check responses. + ### Ollama #### `ENABLE_OLLAMA_API` @@ -1280,8 +1282,11 @@ If you do NOT set this: 4. You will be logged out. **Do not leave this unset in production.** + ::: +:::warning + **Required for Multi-Worker and Multi-Node Deployments AND HIGHLY RECOMMENDED IN SINGLE-WORKER ENVIRONMENTS** 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: @@ -1404,6 +1409,7 @@ When configured, these custom schemes will be validated alongside `http` and `ht - Default: `False` - Description: Determines whether to allow custom models defined on the Hub in their own modeling files. + #### `RAG_RERANKING_MODEL_TRUST_REMOTE_CODE` - Type: `bool` From 7337caaf2437303630306671e7f6f2377328fc98 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 19:28:48 +0100 Subject: [PATCH 65/66] add --- docs/getting-started/env-configuration.mdx | 7 + .../quick-start/tab-kubernetes/Helm.md | 16 +- docs/troubleshooting/multi-replica.mdx | 150 ++++++++++++++++++ 3 files changed, 172 insertions(+), 1 deletion(-) create mode 100644 docs/troubleshooting/multi-replica.mdx diff --git a/docs/getting-started/env-configuration.mdx b/docs/getting-started/env-configuration.mdx index 6c7744c4a..f92c36756 100644 --- a/docs/getting-started/env-configuration.mdx +++ b/docs/getting-started/env-configuration.mdx @@ -5049,6 +5049,13 @@ For configuration using individual parameters or encrypted SQLite, see the relev ::: +:::warning + +**Required for Multi-Replica Setups** +For multi-replica or high-availability deployments (Kubernetes, Docker Swarm), you **MUST** use an external database (PostgreSQL) instead of SQLite. SQLite does not support concurrent writes from multiple instances and will result in database corruption or data inconsistency. + +::: + #### `DATABASE_TYPE` - Type: `str` diff --git a/docs/getting-started/quick-start/tab-kubernetes/Helm.md b/docs/getting-started/quick-start/tab-kubernetes/Helm.md index f0272cbd1..e665db93a 100644 --- a/docs/getting-started/quick-start/tab-kubernetes/Helm.md +++ b/docs/getting-started/quick-start/tab-kubernetes/Helm.md @@ -48,7 +48,21 @@ If you run Open WebUI with multiple replicas/pods (`replicaCount > 1`) or `UVICO ## Access the WebUI -Set up port forwarding or load balancing to access Open WebUI from outside the cluster. +You can access Open WebUI by port-forwarding or configuring an Ingress. + +### Ingress Configuration (Nginx) +If you are using the **NGINX Ingress Controller**, you can enable session affinity (sticky sessions) to improve WebSocket stability. Add the following annotation to your Ingress resource: + +```yaml +metadata: + annotations: + nginx.ingress.kubernetes.io/affinity: "cookie" + nginx.ingress.kubernetes.io/session-cookie-name: "open-webui-session" + nginx.ingress.kubernetes.io/session-cookie-expires: "172800" + nginx.ingress.kubernetes.io/session-cookie-max-age: "172800" +``` + +This ensures that a user's session remains connected to the same pod, reducing issues with WebSocket connections in multi-replica setups (though correct Redis configuration makes this less critical). ## Uninstall diff --git a/docs/troubleshooting/multi-replica.mdx b/docs/troubleshooting/multi-replica.mdx new file mode 100644 index 000000000..052e34c43 --- /dev/null +++ b/docs/troubleshooting/multi-replica.mdx @@ -0,0 +1,150 @@ +--- +sidebar_position: 10 +title: "Multi-Replica / High Availability / Concurrency" +--- + +# Multi-Replica, High Availability & Concurrency Troubleshooting + +This guide addresses common issues encountered when deploying Open WebUI in **multi-replica** environments (e.g., Kubernetes, Docker Swarm) or when using **multiple workers** (`UVICORN_WORKERS > 1`) for increased concurrency. + +## Core Requirements Checklist + +Before troubleshooting specific errors, ensure your deployment meets these **absolute requirements** for a multi-replica setup. Missing any of these will cause instability, login loops, or data loss. + +1. **Shared Secret Key:** [`WEBUI_SECRET_KEY`](/getting-started/env-configuration#webui_secret_key) **MUST** be identical on all replicas. +2. **External Database:** You **MUST** use an external PostgreSQL database (see [`DATABASE_URL`](/getting-started/env-configuration#database_server)). SQLite is **NOT** supported for multiple instances. +3. **Redis for WebSockets:** [`ENABLE_WEBSOCKET_SUPPORT=True`](/getting-started/env-configuration#enable_websocket_support) and [`WEBSOCKET_MANAGER=redis`](/getting-started/env-configuration#websocket_manager) with a valid [`WEBSOCKET_REDIS_URL`](/getting-started/env-configuration#websocket_redis_url) are required. +4. **Shared Storage:** A persistent volume (RWX / ReadWriteMany if possible, or ensuring all replicas map to the same underlying storage for `data/`) is critical for RAG (uploads/vectors) and generated images. +5. **External Vector Database (Recommended):** While embedded Chroma works with shared storage, using a dedicated external Vector DB (e.g., [PGVector](/getting-started/env-configuration#pgvector_db_url), Milvus, Qdrant) is **highly recommended** to avoid file locking issues and improve performance. + +--- + +## Common Issues + +### 1. Login Loops / 401 Unauthorized Errors + +**Symptoms:** +- You log in successfully, but the next click logs you out. +- You see "Unauthorized" or "401" errors in the browser console immediately after login. +- "Error decrypting tokens" appears in logs. + +**Cause:** +Each replica is using a different `WEBUI_SECRET_KEY`. When Replica A issues a session token (JWT), Replica B rejects it because it cannot verify the signature with its own different key. + +**Solution:** +Set the `WEBUI_SECRET_KEY` environment variable to the **same** strong, random string on all backend replicas. + +```yaml +# Example in Kubernetes/Compose +env: + - name: WEBUI_SECRET_KEY + value: "your-super-secure-static-key-here" +``` + +### 2. WebSocket 403 Errors / Connection Failures + +**Symptoms:** +- Chat stops responding or hangs. +- Browser console shows `WebSocket connection failed: 403 Forbidden` or `Connection closed`. +- Logs show `engineio.server: https://your-domain.com is not an accepted origin`. + +**Cause:** +- **CORS:** The load balancer or ingress origin does not match the allowed origins. +- **Missing Redis:** WebSockets are defaulting to in-memory, so events on Replica A (e.g., LLM generation finish) are not broadcast to the user connected to Replica B. + +**Solution:** +1. **Configure CORS:** Ensure [`CORS_ALLOW_ORIGIN`](/getting-started/env-configuration#cors_allow_origin) includes your public domain *and* http/https variations. + + If you see logs like `engineio.base_server:_log_error_once:354 - https://yourdomain.com is not an accepted origin`, you must update this variable. It accepts a **semicolon-separated list** of allowed origins. + + **Example:** + ```bash + CORS_ALLOW_ORIGIN="https://chat.yourdomain.com;http://chat.yourdomain.com;https://yourhostname;http://localhost:3000" + ``` + *Add all valid IPs, Domains, and Hostnames that users might use to access your Open WebUI.* +2. **Enable Redis for WebSockets:** + Ensure these variables are set on **all** replicas: + ```bash + ENABLE_WEBSOCKET_SUPPORT=True + WEBSOCKET_MANAGER=redis + WEBSOCKET_REDIS_URL=redis://your-redis-host:6379/0 + ``` + +### 3. "Model Not Found" or Configuration Mismatch + +**Symptoms:** +- You enable a model or change a setting in the Admin UI, but other users (or you, after a refresh) don't see the change. +- Chats fail with "Model not found" intermittently. + +**Cause:** +- **Configuration Sync:** Replicas are not synced. Open WebUI uses Redis Pub/Sub to broadcast configuration changes (like toggling a model) to all other instances. +- **Missing Redis:** If `REDIS_URL` is not set, configuration changes stay local to the instance where the change was made. + +**Solution:** +Set `REDIS_URL` to point to your shared Redis instance. This enables the Pub/Sub mechanism for real-time config syncing. + +```bash +REDIS_URL=redis://your-redis-host:6379/0 +``` + +### 4. Database Corruption / "Locked" Errors + +**Symptoms:** +- Logs show `database is locked` or severe SQL errors. +- Data saved on one instance disappears on another. + +**Cause:** +Using **SQLite** with multiple replicas. SQLite is a file-based database and does not support concurrent network writes from multiple containers. + +**Solution:** +Migrate to **PostgreSQL**. Update your connection string: + +```bash +DATABASE_URL=postgresql://user:password@postgres-host:5432/openwebui +``` + +### 5. Uploaded Files or RAG Knowledge Inaccessible + +**Symptoms:** +- You upload a file (for RAG) on one instance, but the model cannot find it later. +- Generated images appear as broken links. + +**Cause:** +The `/app/backend/data` directory is not shared or is not consistent across replicas. If User A uploads a file to Replica 1, and the next request hits Replica 2, Replica 2 won't have the file physically on disk. + +**Solution:** +- **Kubernetes:** Use a `PersistentVolumeClaim` with `ReadWriteMany` (RWX) access mode if your storage provider supports it (e.g., NFS, CephFS, AWS EFS). +- **Docker Swarm/Compose:** Mount a shared volume (e.g., NFS mount) to `/app/backend/data` on all containers. + +--- + +## Deployment Best Practices + +### Updates and Migrations + +:::danger Critical: Avoid Concurrent Migrations +**Always scale down to 1 replica (and 1 worker) before upgrading Open WebUI versions.** +::: + +Database migrations run automatically on startup. If multiple replicas (or multiple workers within a single container) start simultaneously with a new version, they may try to run migrations concurrently, leading to race conditions or database schema corruption. + +**Safe Update Procedure:** +1. **Scale Down:** Set replicas to `1` (and ensure `UVICORN_WORKERS=1` if you customized it). +2. **Update Image:** Application restarts with the new version. +3. **Wait for Health Check:** Ensure the single instance starts up fully and completes DB migrations. +4. **Scale Up:** Increase replicas (or `UVICORN_WORKERS`) back to your desired count. + +### Session Affinity (Sticky Sessions) +While Open WebUI is designed to be stateless with proper Redis configuration, enabling **Session Affinity** (Sticky Sessions) at your Load Balancer / Ingress level can improve performance and reduce occasional jitter in WebSocket connections. + +- **Nginx Ingress:** `nginx.ingress.kubernetes.io/affinity: "cookie"` +- **AWS ALB:** Enable Target Group Stickiness. + +--- + +## Related Documentation + +- [Environment Variable Configuration](/getting-started/env-configuration) +- [Troubleshooting Connection Errors](/troubleshooting/connection-error) +- [Logging Configuration](/getting-started/advanced-topics/logging) + From aaecf998dce8c1072f5757163ee36ad0e2c571a7 Mon Sep 17 00:00:00 2001 From: DrMelone <27028174+Classic298@users.noreply.github.com> Date: Sun, 21 Dec 2025 21:25:02 +0100 Subject: [PATCH 66/66] Update sqlite-database.md --- docs/tutorials/tips/sqlite-database.md | 71 +++++++++++++++++--------- 1 file changed, 48 insertions(+), 23 deletions(-) diff --git a/docs/tutorials/tips/sqlite-database.md b/docs/tutorials/tips/sqlite-database.md index 32dae7b78..9a4e8a875 100644 --- a/docs/tutorials/tips/sqlite-database.md +++ b/docs/tutorials/tips/sqlite-database.md @@ -10,7 +10,7 @@ This tutorial is a community contribution and is not supported by the Open WebUI ::: > [!WARNING] -> This documentation was created/updated based on version 0.6.41 and updated for recent migrations. +> This documentation was created/updated based on version 0.6.42 and updated for recent migrations. ## Open-WebUI Internal SQLite Database @@ -59,28 +59,29 @@ Here is a complete list of tables in Open-WebUI's SQLite database. The tables ar | 03 | channel_file | Links files to channels and messages | | 04 | channel_member | Tracks user membership and permissions within channels | | 05 | chat | Stores chat sessions and their metadata | -| 06 | chatidtag | Maps relationships between chats and their associated tags | -| 07 | config | Maintains system-wide configuration settings | -| 08 | document | Stores documents and their metadata for knowledge management | -| 09 | feedback | Captures user feedback and ratings | -| 10 | file | Manages uploaded files and their metadata | -| 11 | folder | Organizes files and content into hierarchical structures | -| 12 | function | Stores custom functions and their configurations | -| 13 | group | Manages user groups and their permissions | -| 14 | group_member | Tracks user membership within groups | -| 15 | knowledge | Stores knowledge base entries and related information | -| 16 | knowledge_file | Links files to knowledge bases | -| 17 | memory | Maintains chat history and context memory | -| 18 | message | Stores individual chat messages and their content | -| 19 | message_reaction | Records user reactions (emojis/responses) to messages | -| 20 | migrate_history | Tracks database schema version and migration records | -| 21 | model | Manages AI model configurations and settings | -| 22 | note | Stores user-created notes and annotations | -| 23 | oauth_session | Manages active OAuth sessions for users | -| 24 | prompt | Stores templates and configurations for AI prompts | -| 25 | tag | Manages tags/labels for content categorization | -| 26 | tool | Stores configurations for system tools and integrations | -| 27 | user | Maintains user profiles and account information | +| 06 | chat_file | Links files to chats and messages | +| 07 | chatidtag | Maps relationships between chats and their associated tags | +| 08 | config | Maintains system-wide configuration settings | +| 09 | document | Stores documents and their metadata for knowledge management | +| 10 | feedback | Captures user feedback and ratings | +| 11 | file | Manages uploaded files and their metadata | +| 12 | folder | Organizes files and content into hierarchical structures | +| 13 | function | Stores custom functions and their configurations | +| 14 | group | Manages user groups and their permissions | +| 15 | group_member | Tracks user membership within groups | +| 16 | knowledge | Stores knowledge base entries and related information | +| 17 | knowledge_file | Links files to knowledge bases | +| 18 | memory | Maintains chat history and context memory | +| 19 | message | Stores individual chat messages and their content | +| 20 | message_reaction | Records user reactions (emojis/responses) to messages | +| 21 | migrate_history | Tracks database schema version and migration records | +| 22 | model | Manages AI model configurations and settings | +| 23 | note | Stores user-created notes and annotations | +| 24 | oauth_session | Manages active OAuth sessions for users | +| 25 | prompt | Stores templates and configurations for AI prompts | +| 26 | tag | Manages tags/labels for content categorization | +| 27 | tool | Stores configurations for system tools and integrations | +| 28 | user | Maintains user profiles and account information | Note: there are two additional tables in Open-WebUI's SQLite database that are not related to Open-WebUI's core functionality, that have been excluded: @@ -166,6 +167,30 @@ Things to know about the channel_file table: | meta | JSON | server_default="{}" | Metadata including tags | | folder_id | Text | nullable | Parent folder ID | +## Chat File Table + +| **Column Name** | **Data Type** | **Constraints** | **Description** | +| --------------- | ------------- | -------------------------------- | --------------------------------- | +| id | Text | PRIMARY KEY | Unique identifier (UUID) | +| user_id | Text | NOT NULL | User associated with the file | +| chat_id | Text | FOREIGN KEY(chat.id), NOT NULL | Reference to the chat | +| file_id | Text | FOREIGN KEY(file.id), NOT NULL | Reference to the file | +| message_id | Text | nullable | Reference to associated message | +| created_at | BigInteger | NOT NULL | Creation timestamp | +| updated_at | BigInteger | NOT NULL | Last update timestamp | + +Things to know about the chat_file table: + +- Unique constraint on (`chat_id`, `file_id`) to prevent duplicate entries +- Foreign key relationships with CASCADE delete +- Indexed on `chat_id`, `file_id`, `message_id`, and `user_id` for performance + +**Why this table was added:** + +- **Query Efficiency**: Before this, files were embedded in message objects. This table allows direct indexed lookups for finding all files in a chat without iterating through every message. +- **Data Consistency**: Acts as a single source of truth for file associations. In multi-node deployments, all nodes query this table instead of relying on potentially inconsistent embedded data. +- **Deduplication**: The database-level unique constraint prevents duplicate file associations, which is more reliable than application-level checks. + ## Chat ID Tag Table | **Column Name** | **Data Type** | **Constraints** | **Description** |