Merge pull request #873 from open-webui/main

docs: Manual Database Migration add Duplicate Column Errors section

docs/enterprise/index.mdx

@@ -38,17 +38,18 @@ Explore how other organizations are driving real impact with Open WebUI.
 
 ## Let’s Talk
 
+:::tip
+To help us respond quickly and efficiently to your inquiry, **please use your official work email address**, Personal email accounts (e.g. gmail.com, hotmail.com, proton.me, icloud.com, yahoo.com etc.) are often flagged by our system and will not be answered.
+:::
+
 **sales@openwebui.com** — Send us your deployment **end user count (seats)**, and let’s explore how we can work together!
 
 :::info
-
 Enterprise licenses and partnership opportunities are available **exclusively to registered entities and organizations**. At this time, we are unable to accommodate individual users. We appreciate your understanding and interest.
 
-To help us respond quickly and efficiently to your inquiry, **please use your official work email address**, Personal email accounts (e.g. gmail.com, hotmail.com, icloud.com, yahoo.com etc.) are often flagged by our system and will not be answered.
-
+**We are not seeking, open to, or in need of any form of disguised collaboration or contribution pitches/offers.** Any attempt to characterize engineering assistance, co-development, or roadmap input **as an alternative to our enterprise licensing program will not receive a response**. All organizational engagement with Open WebUI occurs **solely and exclusively through enterprise licensing**.
 :::
 
-
 Take your AI strategy to the next level with our **premium enterprise solutions**, crafted for organizations that demand **expert consulting, tailored deployment, and dedicated support.**
 
 :::warning

docs/features/rbac/permissions.md

@@ -34,7 +34,7 @@ Chat permissions determine what actions users can perform within chat conversati
 
 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_RAG_WEB_SEARCH`)
+- **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`)
@@ -60,7 +60,7 @@ By default, Open WebUI applies the following permission settings:
 
 **Features Permissions**:
 
-- Web Search: Enabled (`ENABLE_RAG_WEB_SEARCH=True`)
+- 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`)

docs/features/web-search/perplexity_search.mdx

@@ -25,8 +25,20 @@ Perplexity Search API is just a search engine, as opposed to the Perplexity inte
 4. Enter your Perplexity API key from [Perplexity API Key management](https://www.perplexity.ai/account/api/keys).
 5. Press save
 
-:::tip
+### Using LiteLLM for Search
 
-LiteLLM's `/search` endpoint uses the Perplexity Search API style - you can customize the API endpoint of Open WebUI's perplexity_search web search to point to your LiteLLM instance and use that for web searches!
+You can use a [LiteLLM](https://docs.litellm.ai/) proxy instance as your search provider instead of connecting directly to Perplexity. LiteLLM's `/search` endpoint is compatible with the Perplexity Search API style used by Open WebUI.
 
-:::
+To configure this:
+
+1. Follow the setup steps above, selecting `perplexity_search` as the engine.
+2. Under the **Perplexity Search API Base URL** field, replace the default URL with your LiteLLM endpoint.
+3. The URL must follow this specific format: `http://<your-litellm-url>/search/<your-search-provider-name>` - Ensurethe search provider name matches the provider name you configured in your LiteLLM setup.
+
+**Example:**
+
+If your LiteLLM instance is running on localhost and you want to use the `perplexity-search` provider defined in your LiteLLM config:
+
+```
+http://localhost:4000/search/perplexity-search
+```

docs/features/web-search/searxng.md

@@ -21,15 +21,15 @@ To configure SearXNG optimally for use with Open WebUI, follow these steps:
 
 **Step 1: `git clone` SearXNG Docker and navigate to the folder:**
 
-1. Create a New Directory `searxng-docker`
+1. Clone the repository `searxng-docker`
 
- Clone the searxng-docker repository. This folder will contain your SearXNG configuration files. Refer to the [SearXNG documentation](https://docs.searxng.org/) for configuration instructions.
+ Clone the searxng-docker repository. This will create a new directory called `searxng-docker`, which will contain your SearXNG configuration files. Refer to the [SearXNG documentation](https://docs.searxng.org/) for configuration instructions.
 
 ```bash
 git clone https://github.com/searxng/searxng-docker.git
 ```
 
-Navigate to the `searxng-docker` repository:
+Navigate to the `searxng-docker` repository, and run all commands from there:
 
 ```bash
 cd searxng-docker
@@ -49,7 +49,7 @@ cd searxng-docker
 
 # * uncomment LETSENCRYPT_EMAIL, and replace <email> by your email (require to create a Let's Encrypt certificate)
 
-SEARXNG_HOSTNAME=localhost:8080/
+SEARXNG_HOSTNAME=localhost
 
 # LETSENCRYPT_EMAIL=<email>
 
@@ -68,8 +68,18 @@ SEARXNG_HOSTNAME=localhost:8080/
 
 3. Remove the `localhost` restriction by modifying the `docker-compose.yaml` file:
 
+If port 8080 is already in use, change `0.0.0.0:8080` to `0.0.0.0:[available port]` in the command before running it.
+
+Run the appropriate command for your operating system:
+
+- **Linux**
 ```bash
-sed -i "s/127.0.0.1:8080/0.0.0.0:8080/"
+sed -i 's/127.0.0.1:8080/0.0.0.0:8080/' docker-compose.yaml
+```
+
+- **macOS**:
+```bash
+sed -i '' 's/127.0.0.1:8080/0.0.0.0:8080/' docker-compose.yaml
 ```
 
 **Step 4: Grant Necessary Permissions**
@@ -77,13 +87,15 @@ sed -i "s/127.0.0.1:8080/0.0.0.0:8080/"
 4. Allow the container to create new config files by running the following command in the root directory:
 
 ```bash
-sudo chmod a+rwx searxng-docker/searxng
+sudo chmod a+rwx searxng
 ```
 
 **Step 5: Create a Non-Restrictive `limiter.toml` File**
 
 5. Create a non-restrictive `searxng-docker/searxng/limiter.toml` config file:
 
+*If the file already exists, append the missing lines to it.*
+
 <!-- markdownlint-disable-next-line MD033 -->
 <details>
 <!-- markdownlint-disable-next-line MD033 -->
@@ -112,172 +124,74 @@ pass_ip = []
 6. Delete the default `searxng-docker/searxng/settings.yml` file if it exists, as it will be regenerated on the first launch of SearXNG:
 
 ```bash
-rm searxng-docker/searxng/settings.yml
+rm searxng/settings.yml
 ```
 
 **Step 7: Create a Fresh `settings.yml` File**
 
-:::note
-
-On the first run, you must remove `cap_drop: - ALL` from the `docker-compose.yaml` file for the `searxng` service to successfully create `/etc/searxng/uwsgi`.ini. This is necessary because the `cap_drop: - ALL` directive removes all capabilities, including those required for the creation of the `uwsgi.ini` file. After the first run, you should re-add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
-
-:::
-
 7. Bring up the container momentarily to generate a fresh settings.yml file:
 
+If you have multiple containers running with the same name, such as caddy, redis, or searxng, you need to rename them in the docker-compose.yaml file to avoid conflicts.
+
 ```bash
 docker compose up -d ; sleep 10 ; docker compose down
 ```
 
-**Step 8: Add Formats and Update Port Number**
+After the initial run, add `cap_drop: - ALL` to the `docker-compose.yaml` file for security reasons.
+
+If Open WebUI is running in the same Docker network as Searxng, you may remove the `0.0.0.0` and only specify the port mapping. In this case, Open WebUI can access Searxng directly using the container name.
+
+<details>
+<summary>docker-compose.yaml</summary>
+
+```yaml
+searxng:
+    container_name: searxng
+    image: docker.io/searxng/searxng:latest
+    restart: unless-stopped
+    networks:
+      - searxng
+    ports:
+      - "0.0.0.0:8080:8080" # use 8080:8080 if containers are in the same Docker network
+    volumes:
+      - ./searxng:/etc/searxng:rw
+      - searxng-data:/var/cache/searxng:rw
+    environment:
+      - SEARXNG_BASE_URL=https://${SEARXNG_HOSTNAME:-localhost}/
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "1m"
+        max-file: "1"
+    cap_drop:
+      - ALL
+```
+
+</details>
+
+**Step 8: Add Formats**
 
 8. Add HTML and JSON formats to the `searxng-docker/searxng/settings.yml` file:
 
+- **Linux**
 ```bash
-sed -i 's/formats: \[\"html\"\/]/formats: [\"html\", \"json\"]/' searxng-docker/searxng/settings.yml
+sed -i 's/- html/- html\n    - json/' searxng/settings.yml
 ```
 
-Generate a secret key for your SearXNG instance:
+- **macOS**
+```bash
+sed -i '' 's/- html/- html\n    - json/' searxng/settings.yml
+```
+
+**Step 9: Run the Server**
+
+9. Start the container with the following command:
 
 ```bash
-sed -i "s|ultrasecretkey|$(openssl rand -hex 32)|g" searxng-docker/searxng/settings.yml
+docker compose up -d
 ```
 
-Windows users can use the following powershell script to generate the secret key:
-
-```powershell
-$randomBytes = New-Object byte[] 32
-(New-Object Security.Cryptography.RNGCryptoServiceProvider).GetBytes($randomBytes)
-$secretKey = -join ($randomBytes | ForEach-Object { "{0:x2}" -f $_ })
-(Get-Content searxng-docker/searxng/settings.yml) -replace 'ultrasecretkey', $secretKey | Set-Content searxng-docker/searxng/settings.yml
-```
-
-Update the port number in the `server` section to match the one you set earlier (in this case, `8080`):
-
-```bash
-sed -i 's/port: 8080/port: 8080/' searxng-docker/searxng/settings.yml
-```
-
-Change the `bind_address` as desired:
-
-```bash
-sed -i 's/bind_address: "0.0.0.0"/bind_address: "127.0.0.1"/' searxng-docker/searxng/settings.yml
-```
-
-#### Configuration Files
-
-#### searxng-docker/searxng/settings.yml (Extract)
-
-The default `settings.yml` file contains many engine settings. Below is an extract of what the default `settings.yml` file might look like:
-
-<!-- markdownlint-disable-next-line MD033 -->
-<details>
-<!-- markdownlint-disable-next-line MD033 -->
-<summary>searxng-docker/searxng/settings.yml</summary>
-
-```yaml
-
-# see https://docs.searxng.org/admin/settings/settings.html#settings-use-default-settings
-use_default_settings: true
-
-server:
-  # base_url is defined in the SEARXNG_BASE_URL environment variable, see .env and docker-compose.yml
-  secret_key: "ultrasecretkey"  # change this!
-  limiter: true  # can be disabled for a private instance
-  image_proxy: true
-  port: 8080
-  bind_address: "0.0.0.0"
-
-ui:
-  static_use_hash: true
-
-search:
-  safe_search: 0
-  autocomplete: ""
-  default_lang: ""
-  formats:
-    - html
-    - json # json is required
-  # remove format to deny access, use lower case.
-  # formats: [html, csv, json, rss]
-redis:
-  # URL to connect redis database. Is overwritten by ${SEARXNG_REDIS_URL}.
-  # https://docs.searxng.org/admin/settings/settings_redis.html#settings-redis
-  url: redis://redis:6379/0
-```
-
-The port in the settings.yml file for SearXNG should match that of the port number in your docker-compose.yml file for SearXNG.
-
-</details>
-
-**Step 9: Update `uwsgi.ini` File**
-
-9. Ensure your `searxng-docker/searxng/uwsgi.ini` file matches the following:
-
-<!-- markdownlint-disable-next-line MD033 -->
-<details>
-<!-- markdownlint-disable-next-line MD033 -->
-<summary>searxng-docker/searxng/uwsgi.ini</summary>
-
-```ini
-[uwsgi]
-
-# Who will run the code
-uid = searxng
-gid = searxng
-
-# Number of workers (usually CPU count)
-
-# default value: %k (= number of CPU core, see Dockerfile)
-workers = %k
-
-# Number of threads per worker
-
-# default value: 4 (see Dockerfile)
-threads = 4
-
-# The right granted on the created socket
-chmod-socket = 666
-
-# Plugin to use and interpreter config
-single-interpreter = true
-master = true
-plugin = python3
-lazy-apps = true
-enable-threads = 4
-
-# Module to import
-module = searx.webapp
-
-# Virtualenv and python path
-pythonpath = /usr/local/searxng/
-chdir = /usr/local/searxng/searx/
-
-# automatically set processes name to something meaningful
-auto-procname = true
-
-# Disable request logging for privacy
-disable-logging = true
-log-5xx = true
-
-# Set the max size of a request (request-body excluded)
-buffer-size = 8192
-
-# No keep alive
-
-# See https://github.com/searx/searx-docker/issues/24
-add-header = Connection: close
-
-# uwsgi serves the static files
-static-map = /static=/usr/local/searxng/searx/static
-
-# expires set to one day
-static-expires = /* 86400
-static-gzip-all = True
-offload-threads = 4
-```
-
-</details>
+The searXNG will be available at http://localhost:8080 (or the port number you set earlier).
 
 ## 2. Alternative Setup
 
@@ -412,6 +326,7 @@ docker exec -it open-webui curl http://host.docker.internal:8080/search?q=this+i
 3. Set `Web Search Engine` from dropdown menu to `searxng`
 4. Set `Searxng Query URL` to one of the following examples:
 
+- `http://localhost:8080/search?q=<query>` (using the host and host port, suitable for Docker-based setups)
 - `http://searxng:8080/search?q=<query>` (using the container name and exposed port, suitable for Docker-based setups)
 - `http://host.docker.internal:8080/search?q=<query>` (using the `host.docker.internal` DNS name and the host port, suitable for Docker-based setups)
 - `http://<searxng.local>/search?q=<query>` (using a local domain name, suitable for local network access)
@@ -426,7 +341,7 @@ docker exec -it open-webui curl http://host.docker.internal:8080/search?q=this+i
 
 ## 5. Using Web Search in a Chat
 
-To access Web Search, Click on the + next to the message input field.
+To access Web Search, Click the Integrations button next to the + icon.
 
 Here you can toggle Web Search On/Off.
 

docs/features/workspace/models.md

@@ -94,7 +94,7 @@ From the main list view in the `Models` section, click the ellipsis (`...`) next
 - **Clone**: Create a copy of a model configuration, which will be appended with `-clone`.
 
 :::note
-You cannot clone a raw Base Model directly; you must create a custom model first before cloning it.
+A raw Base Model can be cloned as a custom Workspace model, but it will not clone the raw Base Model itself.
 :::
 
 - **Copy Link**: Copies a direct URL to the model settings.

docs/getting-started/env-configuration.mdx

@@ -2208,7 +2208,7 @@ The old individual environment variables (`DOCLING_OCR_ENGINE`, `DOCLING_OCR_LAN
   - `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` (str): OCR language codes (e.g., `eng,fra,deu,spa`)
+  - `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
@@ -2223,8 +2223,10 @@ The old individual environment variables (`DOCLING_OCR_ENGINE`, `DOCLING_OCR_LAN
 {
   "do_ocr": true,
   "ocr_engine": "tesseract",
-  "ocr_lang": "eng,fra,deu,spa",
+  "ocr_lang": ["eng", "fra", "deu", "spa"],
   "force_ocr": false,
+  "pdf_backend": "dlparse_v4",
+  "table_mode": "accurate",
   "do_picture_description": true,
   "picture_description_mode": "api",
   "vlm_pipeline_model_api": "openai://gpt-4o"
@@ -3104,8 +3106,8 @@ the search query. Example: `http://searxng.local/search?q=<query>`
 
 - Type: `str`
 - Default: `https://api.perplexity.ai/search`
-- Description: Configures the API endpoint for Perplexity Search. Allows using custom or self-hosted Perplexity-compatible API endpoints (such as LiteLLM's `/search` endpoint) instead of the hardcoded default. This enables flexibility in routing search requests to alternative providers or internal proxies.
-- Example: `my-litellm-server.com/search`
+- Description: Configures the API endpoint for Perplexity Search. Allows using custom or self-hosted Perplexity-compatible API endpoints (such as LiteLLM's `/search` endpoint) instead of the hardcoded default for the official Perplexity API. This enables flexibility in routing search requests to alternative providers or internal proxies. **Note: If using LiteLLM, append the specific provider name to the URL path.**
+- Example: `http://my-litellm-server.com/search/perplexity-search`
 - Persistence: This environment variable is a `PersistentConfig` variable.
 
 #### `PERPLEXITY_MODEL`

docs/getting-started/updating.mdx

@@ -3,62 +3,155 @@ sidebar_position: 300
 title: "Updating Open WebUI"
 ---
 
-## Why isn't my Open WebUI updating?
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
 
-To update your local Docker installation of Open WebUI to the latest version available, you can either use **Watchtower** or manually update the container. Follow either of the steps provided below to be guided through updating your existing Open WebUI image.
+## Overview
 
-### Manual Update
+Keeping Open WebUI updated ensures you have the latest features, security patches, and bug fixes. You can update manually or automate the process using container update tools.
 
-1. **Stop and remove the current container**:
+:::info Before Updating
+- **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
+:::
 
-   This will stop the running container and remove it, but it won't delete the data stored in the Docker volume. (Replace `open-webui` with your container's name throughout the updating process if it's different for you.)
+## Manual Update
 
-```bash
+Manual updates give you complete control and are recommended for production environments or when you need to review changes before applying them.
+
+### Step 1: Stop and Remove Current Container
+
+This stops the running container and removes it without deleting your data stored in the Docker volume.
+
+```bash title="Terminal"
+# Replace 'open-webui' with your container name if different
+# Use 'docker ps' to find your container name if unsure
 docker rm -f open-webui
 ```
 
-2. **Pull the latest Docker image**:
-
-   This will update the Docker image, but it won't update the running container or its data.
-
+:::tip Find Your Container Name
+If your container isn't named `open-webui`, find it with:
 ```bash
+docker ps -a | grep open-webui
+```
+Look in the "NAMES" column for your actual container name.
+:::
+
+### Step 2: Pull Latest Docker Image
+
+Download the newest Open WebUI image from the container registry.
+
+```bash title="Terminal"
 docker pull ghcr.io/open-webui/open-webui:main
 ```
 
-:::info
-
-**Remove any existing data in the Docker volume (NOT RECOMMENDED UNLESS ABSOLUTELY NECCESSARY!)**. Skip this step entirely if not needed and move on to the last step:
-
-   If you want to start with a clean slate, you can remove the existing data in the Docker volume. Be careful, as this will delete all your chat histories and other data.
-
-   The data is stored in a Docker volume named `open-webui`. You can remove it with the following command:
-
-```bash
-docker volume rm open-webui
+**Expected output:**
+```
+main: Pulling from open-webui/open-webui
+Digest: sha256:abc123...
+Status: Downloaded newer image for ghcr.io/open-webui/open-webui:main
 ```
 
+:::note About Data Persistence
+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.
 :::
 
-3. **Start the container again with the updated image and existing volume attached**:
+### Step 3: Start Container with Updated Image
 
-   If you didn't remove the existing data, this will start the container with the updated image and the existing data. If you removed the existing data, this will start the container with the updated image and a new, empty volume. **For Nvidia GPU support, add `--gpus all` to the docker run command**
+Recreate the container using the new image while mounting your existing data volume.
 
-```bash
-docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main
+<Tabs groupId="gpu-support">
+  <TabItem value="cpu" label="CPU Only" default>
+
+```bash title="Terminal - Standard Deployment"
+docker run -d \
+  -p 3000:8080 \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  ghcr.io/open-webui/open-webui:main
 ```
 
-## Keeps being logged out after every update?
-If you find yourself getting logged out after every update, ensure that `WEBUI_SECRET_KEY` is set in your environment variables. Without this key being consistently defined, your authentication sessions may be invalidated after updates.
+  </TabItem>
+  <TabItem value="nvidia" label="NVIDIA GPU">
 
-To set `WEBUI_SECRET_KEY` persistently, include it when running your Docker container:
-
-```bash
-docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui -e WEBUI_SECRET_KEY=your_secret_key ghcr.io/open-webui/open-webui:main
+```bash title="Terminal - With NVIDIA GPU Support"
+docker run -d \
+  -p 3000:8080 \
+  --gpus all \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  ghcr.io/open-webui/open-webui:main
 ```
 
-Or, if using **docker-compose**, add it under the `environment` section:
+  </TabItem>
+</Tabs>
 
-```yml
+:::warning About WEBUI_SECRET_KEY
+If you're not setting `WEBUI_SECRET_KEY`, it will be auto-generated each time you recreate the container, **causing you to be logged out after every update**.
+
+See the [Persistent Login Sessions](#persistent-login-sessions) section below to fix this.
+:::
+
+### Verify Update Success
+
+Check that Open WebUI started successfully:
+
+```bash title="Terminal - Check Container Logs"
+docker logs open-webui
+
+# Watch logs in real-time
+docker logs -f open-webui
+```
+
+**Successful startup indicators:**
+```
+INFO:     [db] Database initialization complete
+INFO:     [main] Open WebUI starting on http://0.0.0.0:8080
+```
+
+Then verify in your browser:
+1. Navigate to `http://localhost:3000` (or your configured port)
+2. Clear browser cache (Ctrl+Shift+Delete or Cmd+Shift+Delete)
+3. Hard refresh the page (Ctrl+F5 or Cmd+Shift+R)
+4. Log in and verify your data is intact
+
+## Persistent Login Sessions
+
+To avoid being logged out after every update, you must set a persistent `WEBUI_SECRET_KEY`.
+
+### Generate and Set Secret Key
+
+<Tabs groupId="setup-method">
+  <TabItem value="docker-run" label="Docker Run" default>
+
+```bash title="Terminal - Docker Run with Secret Key"
+docker run -d \
+  -p 3000:8080 \
+  -v open-webui:/app/backend/data \
+  --name open-webui \
+  --restart always \
+  -e WEBUI_SECRET_KEY="your-secret-key-here" \
+  ghcr.io/open-webui/open-webui:main
+```
+
+:::tip Generate a Secure Key
+Generate a cryptographically secure key with:
+```bash
+openssl rand -hex 32
+```
+Or use Python:
+```bash
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+:::
+
+  </TabItem>
+  <TabItem value="docker-compose" label="Docker Compose">
+
+```yaml title="docker-compose.yml"
 version: '3'
 services:
   open-webui:
@@ -68,40 +161,83 @@ services:
     volumes:
       - open-webui:/app/backend/data
     environment:
-      - WEBUI_SECRET_KEY=your_secret_key
+      - WEBUI_SECRET_KEY=your-secret-key-here
+    restart: unless-stopped
+
+volumes:
+  open-webui:
 ```
 
-For more details on environment variable settings, check the [Open WebUI documentation on security variables](https://docs.openwebui.com/getting-started/env-configuration#security-variables).
+  </TabItem>
+</Tabs>
 
-## Automatically Updating Open WebUI with Watchtower
+:::danger Store Secret Key Securely
+- **Never commit** your secret key to version control
+- Use environment files (`.env`) or secret management tools
+- Keep the same key across updates to maintain sessions
+:::
 
-You can use [Watchtower](https://containrrr.dev/watchtower/) to automate the update process for Open WebUI. Here are three options:
+For complete environment variable documentation, see [Environment Configuration](https://docs.openwebui.com/getting-started/env-configuration#security-variables).
 
-### Option 1: One-time Update
+## Automated Update Tools
 
-You can run Watchtower as a one-time update to stop the current container, pull the latest image, and start a new container with the updated image and existing volume attached (**For Nvidia GPU support, add `--gpus all` to the docker run command**):
+Automated updates can save time but require careful consideration of the trade-offs.
 
-```bash
-docker run --rm --volume /var/run/docker.sock:/var/run/docker.sock containrrr/watchtower --run-once open-webui
-```
+:::warning Important Considerations
+**Automated updates can break your deployment if:**
+- A new version has breaking changes you haven't reviewed
+- Custom configurations become incompatible
+- Database migrations fail during unattended updates
+- You have plugins or customizations that aren't forward-compatible
 
-### Option 2: Running Watchtower as a Separate Container
+**Best practices:**
+- Always review release notes before auto-updating production systems
+- Test updates in a staging environment first
+- Consider notification-only tools rather than automatic updates
+- Have a rollback plan and recent backups
+:::
 
-You can run Watchtower as a separate container that watches and updates your Open WebUI container:
+### Option 1: Watchtower (Community Fork)
 
-```bash
-docker run -d --name watchtower \
+:::info Watchtower Status
+The original `containrrr/watchtower` is **no longer maintained** and **does not work with Docker 29+**. The community has created maintained forks that resolve these issues.
+:::
+
+The original Watchtower project hasn't received updates in over two years and fails with Docker version 29.0.0 or newer due to API version incompatibility. Two maintained forks are now available: nickfedor/watchtower and Marrrrrrrrry/watchtower, both compatible with Docker 29+.
+
+**Recommended: nickfedor/watchtower fork**
+
+<Tabs>
+  <TabItem value="one-time" label="One-Time Update" default>
+
+Run Watchtower once to update all containers, then exit:
+
+```bash title="Terminal - One-Time Update"
+docker run --rm \
   --volume /var/run/docker.sock:/var/run/docker.sock \
-  containrrr/watchtower -i 300 open-webui
+  nickfedor/watchtower \
+  --run-once open-webui
 ```
 
-This will start Watchtower in detached mode, watching your Open WebUI container for updates every 5 minutes.
+  </TabItem>
+  <TabItem value="continuous" label="Continuous Monitoring">
 
-### Option 3: Integrating Watchtower with a `docker-compose.yml` File
+Run Watchtower as a persistent container that checks for updates every 6 hours:
 
-You can also integrate Watchtower with your `docker-compose.yml` file to automate updates for Open WebUI (**For Nvidia GPU support, add `--gpus all` to the docker run command**):
+```bash title="Terminal - Continuous Watchtower"
+docker run -d \
+  --name watchtower \
+  --restart unless-stopped \
+  --volume /var/run/docker.sock:/var/run/docker.sock \
+  nickfedor/watchtower \
+  --interval 21600 \
+  open-webui
+```
 
-```yml
+  </TabItem>
+  <TabItem value="compose" label="Docker Compose">
+
+```yaml title="docker-compose.yml"
 version: '3'
 services:
   open-webui:
@@ -110,12 +246,20 @@ services:
       - "3000:8080"
     volumes:
       - open-webui:/app/backend/data
+    environment:
+      - WEBUI_SECRET_KEY=your-secret-key-here
+    restart: unless-stopped
 
   watchtower:
-    image: containrrr/watchtower
+    image: nickfedor/watchtower:latest
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
-    command: --interval 300 open-webui
+    environment:
+      - WATCHTOWER_CLEANUP=true
+      - WATCHTOWER_INCLUDE_STOPPED=false
+      - WATCHTOWER_SCHEDULE=0 0 2 * * *  # 2 AM daily
+    command: open-webui
+    restart: unless-stopped
     depends_on:
       - open-webui
 
@@ -123,29 +267,311 @@ volumes:
   open-webui:
 ```
 
-In this example, Watchtower is integrated with the `docker-compose.yml` file and watches the Open WebUI container for updates every 5 minutes.
+  </TabItem>
+</Tabs>
 
-:::info
+**Watchtower configuration options:**
 
-After updating, it's a good practice to clear your browser cache to ensure you are running the latest version of the web interface.
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `WATCHTOWER_CLEANUP` | Remove old images after update | `false` |
+| `WATCHTOWER_INCLUDE_STOPPED` | Update stopped containers too | `false` |
+| `WATCHTOWER_SCHEDULE` | Cron expression for update schedule | `0 0 0 * * *` (midnight) |
+| `WATCHTOWER_MONITOR_ONLY` | Only notify, don't update | `false` |
 
+:::tip Monitor-Only Mode
+To receive notifications without automatic updates:
+```bash
+docker run -d \
+  --name watchtower \
+  --volume /var/run/docker.sock:/var/run/docker.sock \
+  -e WATCHTOWER_MONITOR_ONLY=true \
+  -e WATCHTOWER_NOTIFICATIONS=email \
+  -e WATCHTOWER_NOTIFICATION_EMAIL_TO=you@example.com \
+  nickfedor/watchtower
+```
 :::
 
-## Persistent Data in Docker Volumes
+**Alternative fork:** Marrrrrrrrry/watchtower is another actively maintained fork with updated dependencies and simplified functions.
 
-The data is stored in a Docker volume named `open-webui`. The path to the volume is not directly accessible, but you can inspect the volume with the following command:
+For complete Watchtower documentation, visit https://watchtower.nickfedor.com/
 
+### Option 2: What's Up Docker (WUD)
+
+What's Up Docker (WUD) is a notification-focused alternative that doesn't automatically update containers but instead provides a web UI to monitor updates and trigger them manually.
+
+**Why choose WUD:**
+- ✅ Web UI for visual monitoring
+- ✅ Click-button manual updates
+- ✅ Shows descriptive names and changelogs
+- ✅ Auto-prunes old images
+- ✅ Supports multiple Docker hosts
+- ✅ Extensive notification options
+- ❌ Requires manual intervention (not fully automated)
+
+**Quick start with WUD:**
+
+```yaml title="docker-compose.yml"
+version: '3'
+services:
+  wud:
+    image: fmartinou/whats-up-docker:latest
+    container_name: wud
+    ports:
+      - "3001:3000"
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      # Authentication (optional but recommended)
+      - WUD_AUTH_BASIC_USER=admin
+      - WUD_AUTH_BASIC_HASH=$$apr1$$... # Generate with htpasswd
+      
+      # Enable triggers for updates
+      - WUD_TRIGGER_DOCKERCOMPOSE_WUD_FILE=/docker-compose.yml
+      
+      # Notification examples
+      - WUD_WATCHER_LOCAL_SOCKET=/var/run/docker.sock
+    restart: unless-stopped
+```
+
+After starting WUD, access the web interface at `http://localhost:3001`. You'll see all containers and available updates with click-to-update buttons.
+
+:::tip Generate Password Hash
 ```bash
+htpasswd -nbB admin yourpassword
+```
+Copy the part after the colon, and replace each `$` with `$$` in docker-compose.
+:::
+
+For complete WUD documentation, visit https://getwud.github.io/wud/
+
+### Option 3: Diun (Docker Image Update Notifier)
+
+Diun is a lightweight CLI tool that only sends notifications about available updates without performing any updates. It's ideal if you want complete control and just need alerts.
+
+**Why choose Diun:**
+- ✅ Notification-only (safest approach)
+- ✅ No web UI overhead (lightweight)
+- ✅ Multiple notification providers (email, Slack, Discord, Telegram, etc.)
+- ✅ Fine-grained control over what to monitor
+- ❌ No built-in update mechanism (purely informational)
+
+```yaml title="docker-compose.yml"
+version: '3'
+services:
+  diun:
+    image: crazymax/diun:latest
+    container_name: diun
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./data:/data
+    environment:
+      - TZ=America/New_York
+      - LOG_LEVEL=info
+      - DIUN_WATCH_WORKERS=10
+      - DIUN_WATCH_SCHEDULE=0 */6 * * *  # Every 6 hours
+      - DIUN_PROVIDERS_DOCKER=true
+      - DIUN_NOTIF_MAIL_HOST=smtp.gmail.com
+      - DIUN_NOTIF_MAIL_PORT=587
+      - DIUN_NOTIF_MAIL_USERNAME=your-email@gmail.com
+      - DIUN_NOTIF_MAIL_PASSWORD=your-app-password
+      - DIUN_NOTIF_MAIL_FROM=your-email@gmail.com
+      - DIUN_NOTIF_MAIL_TO=your-email@gmail.com
+    restart: unless-stopped
+```
+
+For complete Diun documentation, visit https://crazymax.dev/diun/
+
+### Comparison: Which Tool Should You Use?
+
+| Feature | Watchtower (Fork) | WUD | Diun |
+|---------|------------------|-----|------|
+| **Automatic Updates** | ✅ Yes | ⚠️ Manual via UI | ❌ No |
+| **Web Interface** | ❌ No | ✅ Yes | ❌ No |
+| **Notifications** | ✅ Yes | ✅ Yes | ✅ Yes |
+| **Manual Control** | ⚠️ Limited | ✅ Full control | ✅ Full control |
+| **Resource Usage** | Low | Medium | Very Low |
+| **Docker 29+ Support** | ✅ Yes (forks) | ✅ Yes | ✅ Yes |
+| **Best For** | Set-and-forget homelabs | Visual monitoring + control | Notification-only workflows |
+
+:::tip Recommendation
+- **For homelabs/personal use:** nickfedor/watchtower (automated)
+- **For managed environments:** WUD (visual + manual control)
+- **For production/critical systems:** Diun (notifications only) + manual updates
+:::
+
+## Troubleshooting Updates
+
+### Container Won't Start After Update
+
+**Check logs for errors:**
+```bash title="Terminal"
+docker logs open-webui
+
+# Look for migration errors or startup failures
+```
+
+**Common causes:**
+- Database migration failed
+- Incompatible environment variables
+- Port already in use
+
+**Solution:** Restore previous version and investigate:
+```bash title="Terminal - Rollback to Previous Version"
+# Stop current container
+docker stop open-webui
+docker rm open-webui
+
+# Pull specific older version (check GitHub releases for version tags)
+docker pull ghcr.io/open-webui/open-webui:v0.4.0
+
+# Start with old image
+docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
+  --name open-webui ghcr.io/open-webui/open-webui:v0.4.0
+```
+
+### Data Loss or Corruption
+
+**If you suspect data issues:**
+
+```bash title="Terminal - Inspect Volume"
+# Find volume location
+docker volume inspect open-webui
+
+# Check database file exists
+docker run --rm -v open-webui:/data alpine ls -lah /data
+```
+
+**Recovery steps:**
+1. Stop Open WebUI: `docker stop open-webui`
+2. Backup volume: `docker run --rm -v open-webui:/data -v $(pwd):/backup alpine tar czf /backup/openwebui-backup.tar.gz /data`
+3. Restore from backup if needed
+4. Check [Manual Migration Guide](./manual-database-migration) for database issues
+
+### Watchtower Updates Too Frequently
+
+Configure update schedule with cron expressions:
+
+```bash title="Terminal - Custom Schedule"
+# Daily at 3 AM
+-e WATCHTOWER_SCHEDULE="0 0 3 * * *"
+
+# Weekly on Sundays at 2 AM
+-e WATCHTOWER_SCHEDULE="0 0 2 * * 0"
+
+# Every 12 hours
+-e WATCHTOWER_SCHEDULE="0 0 */12 * * *"
+```
+
+### "Logged Out After Update" Despite Setting Secret Key
+
+**Diagnosis:**
+```bash title="Terminal - Check Environment Variables"
+docker inspect open-webui | grep WEBUI_SECRET_KEY
+```
+
+If the key isn't showing, you didn't pass it correctly when recreating the container.
+
+**Fix:**
+```bash title="Terminal - Recreate with Correct Key"
+docker stop open-webui
+docker rm open-webui
+
+# Make sure to include -e WEBUI_SECRET_KEY
+docker run -d -p 3000:8080 -v open-webui:/app/backend/data \
+  -e WEBUI_SECRET_KEY="your-persistent-key" \
+  --name open-webui ghcr.io/open-webui/open-webui:main
+```
+
+## Docker Volume Management
+
+### Locate Your Data
+
+The `open-webui` Docker volume contains all your data (chats, users, uploads, etc.).
+
+```bash title="Terminal - Inspect Volume"
 docker volume inspect open-webui
 ```
 
-This will show you the details of the volume, including the mountpoint, which is usually located in `/var/lib/docker/volumes/open-webui/_data`.
+**Common volume locations:**
+- Linux: `/var/lib/docker/volumes/open-webui/_data`
+- Windows (WSL2): `\\wsl$\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes\open-webui\_data`
+- macOS: `~/Library/Containers/com.docker.docker/Data/vms/0/data/docker/volumes/open-webui/_data`
 
-On Windows 10 + WSL 2, Docker volumes are located here (type in the Windows file explorer):
-- \\\wsl$\docker-desktop\mnt\docker-desktop-disk\data\docker\volumes
+:::warning Direct Access Risk
+Avoid directly modifying files in the volume location. Always interact through the container or Docker commands to prevent corruption.
+:::
 
-For older versions of Docker (pre-Docker v26.1.4):
-- \\\wsl$\docker-desktop-data\data\docker\volumes
-- \\\wsl$\docker-desktop-data\version-pack-data\community\docker\volumes
+### Backup Volume
 
-*(Windows answer credit to StackOverflow user sarye-haddadi; [link to original SO post](https://stackoverflow.com/questions/43181654/locating-data-volumes-in-docker-desktop-windows))*
+```bash title="Terminal - Backup Docker Volume"
+# Create timestamped backup
+docker run --rm \
+  -v open-webui:/data \
+  -v $(pwd):/backup \
+  alpine tar czf /backup/openwebui-$(date +%Y%m%d_%H%M%S).tar.gz /data
+```
+
+### Restore Volume
+
+```bash title="Terminal - Restore from Backup"
+# Stop container
+docker stop open-webui
+
+# Restore backup
+docker run --rm \
+  -v open-webui:/data \
+  -v $(pwd):/backup \
+  alpine sh -c "rm -rf /data/* && tar xzf /backup/openwebui-20241201_120000.tar.gz -C /"
+
+# Start container
+docker start open-webui
+```
+
+### Clean Up Old Images
+
+After updating, old images remain on disk. Remove them to free space:
+
+```bash title="Terminal - Remove Unused Images"
+# Remove dangling images (not tagged or used)
+docker image prune
+
+# Remove all unused images (careful!)
+docker image prune -a
+
+# List all open-webui images
+docker images | grep open-webui
+```
+
+Watchtower can do this automatically with:
+```bash
+-e WATCHTOWER_CLEANUP=true
+```
+
+## Post-Update Checklist
+
+After updating, verify everything works:
+
+- [ ] Open WebUI starts without errors (`docker logs open-webui`)
+- [ ] Can access web interface at `http://localhost:3000`
+- [ ] Can log in with existing credentials
+- [ ] Chat history is intact
+- [ ] Models are still configured correctly
+- [ ] Custom settings are preserved
+- [ ] No JavaScript console errors (F12 in browser)
+- [ ] Clear browser cache if interface looks broken
+
+:::tip Browser Cache Issues
+If the interface looks broken or old after updating:
+1. Hard refresh: Ctrl+F5 (Windows/Linux) or Cmd+Shift+R (Mac)
+2. Clear site data: Browser Settings > Privacy > Clear browsing data
+3. Try incognito/private window to verify it's a cache issue
+:::
+
+## Additional Resources
+
+- [Open WebUI GitHub Releases](https://github.com/open-webui/open-webui/releases) - Version history and changelogs
+- [Environment Configuration Guide](https://docs.openwebui.com/getting-started/env-configuration) - All environment variables
+- [Manual Database Migration](troubleshooting/manual-database-migration.md) - Fix database issues after updates
+- [Watchtower Documentation](https://watchtower.nickfedor.com/) - Advanced Watchtower configuration
+- [WUD Documentation](https://getwud.github.io/wud/) - What's Up Docker setup guide

docs/license.mdx

@@ -13,7 +13,7 @@ import { TopBanners } from "@site/src/components/TopBanners";
 :::tip
 **Here's the TL;DR:**
 
-To keep Open WebUI thriving for the long term, we’ve introduced a **lightweight branding protection clause** with Open WebUI v0.6.6+ that helps us sustain the project while ensuring **every user** continues to benefit from rapid innovation **without resorting to gated features or paywalled functionality**. Branding requirements **only apply to larger deployments (50+ users)**. Deployments with 50 or fewer users may fully rebrand if they choose.
+To keep Open WebUI thriving for the long term, we’ve introduced a **lightweight branding protection clause** with Open WebUI v0.6.6+ that helps us sustain the project while ensuring **every user** continues to benefit from rapid innovation **without resorting to gated features or paywalled functionality**. Branding requirements **only apply to larger deployments (50+ users, aggregate)**. Self-hosted internal deployments with 50 or fewer users may fully rebrand if they choose.
 
 As a small, independent team building mission-critical AI tooling, we rely on fair attribution to **support ongoing development, security, and quality**, all without restricting real users, contributors, or businesses who use Open WebUI responsibly.
 
@@ -31,7 +31,7 @@ In plain terms:
 - **You can still use, modify, and redistribute it for any purpose, just don’t remove or alter our branding unless you meet one of three clear criteria (see below).**
 - **The original BSD-3 license continues to apply for all contributions made to the codebase up to and including release v0.6.5.**
 
-We remain committed to transparency, openness, and supporting everyone, from hobbyists to enterprise. This is a “semi-copyleft” measure: we protect just the branding, to keep the project honest and sustainable; everything else is as free as you expect from open-source BSD.
+We remain committed to transparency, openness, and supporting everyone, from hobbyists to enterprise. This is a “semi-copyleft” measure: we protect just the branding, to keep the project honest and sustainable; everything else is as free as you expect from open-source.
 
 We take your trust seriously. We want Open WebUI to stay **empowering and accessible**, **driven by real community spirit**, not gated, not locked-in, not co-opted by bad actors. We’re a small, lean team, but we care deeply about giving all our users the best experience and keeping our ecosystem clean and fair. **Thank you for supporting us, and for caring about the future of open AI.**
 
@@ -157,9 +157,9 @@ BSD-3 output/forks have **maximum flexibility**: as long as you keep the origina
 
 ### 6. Does this mean Open WebUI is “no longer open source”?
 
-It's a great, and complicated, question, because **"open source" can mean many different things to many people**.
+It's a great, and complicated, question, because "open source" can mean many different things to many people.
 
-- **In the narrowest, most “by-the-book” sense, our new branding clause means Open WebUI v0.6.6+ isn’t OSI-certified "open source.”**
+- In the narrowest, most “by-the-book” sense, our new branding clause means: **No, Open WebUI v0.6.6+ isn’t OSI-certified "open source.”**
     - Example: The OSI would not certify licenses that require you to keep original branding.
 
 - However, compared to what most people mean in practice ,  **“is the code available, can I use it, fork it, change it, build things with it, and not pay you or get a special key?”** ,  the answer is still a resounding **yes**.

docs/tutorials/integrations/mcp-notion.mdx

@@ -19,12 +19,168 @@ This integration utilizes the official Notion MCP server, which specializes in *
 This tutorial is a community contribution and is not supported by the Open WebUI team. It serves 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/).
 :::
 
-## Prerequisites
+## Method 1: Streamable HTTP (Recommended)
 
-Regardless of the connection method chosen, you must first create an internal integration within Notion.
+This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers.
 
-### 1. Create Internal Integration
-1.  Navigate to [Notion My Integrations](https://www.notion.so/my-integrations).
+:::info Preferred Method
+**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.
+:::
+
+### 1. Configure Tool
+You can automatically prefill the connection settings by importing the JSON configuration below.
+
+1.  Navigate to **Admin Panel > Settings > External Tools**.
+2.  Click the **+** (Plus) button to add a new tool.
+3.  Click **Import** (top right of the modal).
+4.  Paste the following JSON snippet:
+
+```json title="Notion Remote MCP Configuration"
+[
+  {
+    "type": "mcp",
+    "url": "https://mcp.notion.com/mcp",
+    "spec_type": "url",
+    "spec": "",
+    "path": "openapi.json",
+    "auth_type": "oauth_2.1",
+    "key": "",
+    "info": {
+      "id": "ntn",
+      "name": "Notion",
+      "description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content."
+    }
+  }
+]
+```
+
+5.  **Register:** Click the **Register Client** button (next to the Auth dropdown).
+6.  Click **Save**.
+
+![Open WebUI Tool Config: Shows the External Tools modal with the JSON imported and Register Client button highlighted.](/images/mcp-notion/notion-setup-step5.png)
+
+### 2. Authenticate & Grant Access
+Once the tool is added, you must authenticate to link your specific workspace.
+
+1.  Open any chat window.
+2.  Click the **+** (Plus) button in the chat input bar.
+3.  Navigate to **Integrations > Tools**.
+4.  Toggle the **Notion** switch to **ON**.
+
+![Chat Interface Toggle: Shows the chat input bar with the '+' menu open, 'Integrations' selected, and the 'Notion' tool toggled ON.](/images/mcp-notion/notion-setup-step6.png)
+
+5.  **Authorize:** You will be redirected to a "Connect with Notion MCP" screen.
+    *   Ensure the correct **Workspace** is selected in the dropdown.
+    *   Click **Continue**.
+
+:::note Security: Frequent Re-authentication
+For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error. 
+
+This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revisit the steps above to complete the "Connect with Notion MCP" authorization flow again.
+:::
+
+![Notion OAuth Screen: Shows the 'Connect with Notion MCP' authorization page with the workspace dropdown selected.](/images/mcp-notion/notion-setup-step7.png)
+
+---
+
+## Method 2: Self-Hosted via MCPO (Advanced)
+
+This method is for advanced users who prefer to run the MCP server locally within their own infrastructure using **MCPO**. Unlike Streamable HTTP, this method requires you to manually manage your own credentials.
+
+Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server locally (using Docker or Node.js) within your infrastructure, you must use **MCPO** to bridge the connection.
+
+:::info Prerequisites
+To use this method, you must first create an internal integration to obtain a **Secret Key**. Please complete the **[Creating an Internal Integration](#creating-an-internal-integration)** section below before proceeding with the configuration steps here.
+:::
+
+### 1. Configure MCPO
+Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running. Configure your MCPO instance to run the Notion server using one of the runtimes below by adding the JSON block to your `mcpo-config.json` file.
+
+**Note:** Replace `secret_YOUR_KEY_HERE` with the secret obtained from the [Creating an Internal Integration](#creating-an-internal-integration) section.
+
+<Tabs>
+  <TabItem value="npx" label="Node (npx)" default>
+    This configuration uses the official Node.js package.
+
+    ```json title="mcpo-config.json"
+    {
+      "mcpServers": {
+        "notion": {
+          "command": "npx",
+          "args": [
+            "-y",
+            "@notionhq/notion-mcp-server"
+          ],
+          "env": {
+            "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </TabItem>
+  <TabItem value="docker" label="Docker">
+    This configuration uses the official Docker image.
+
+    ```json title="mcpo-config.json"
+    {
+      "mcpServers": {
+        "notion": {
+          "command": "docker",
+          "args": [
+            "run",
+            "--rm",
+            "-i",
+            "-e",
+            "NOTION_TOKEN",
+            "mcp/notion"
+          ],
+          "env": {
+            "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
+          }
+        }
+      }
+    }
+    ```
+  </TabItem>
+</Tabs>
+
+### 2. Connect Open WebUI
+Once MCPO is running and configured with Notion:
+
+1.  Navigate to **Admin Panel > Settings > External Tools**.
+2.  Click the **+** (Plus) button.
+3.  Click **Import** (top right of the modal).
+4.  Paste the following JSON snippet (update the URL with your MCPO address):
+
+```json title="MCPO Connection JSON"
+[
+  {
+    "type": "openapi",
+    "url": "http://<YOUR_MCPO_IP>:<PORT>/notion",
+    "spec_type": "url",
+    "spec": "",
+    "path": "openapi.json",
+    "auth_type": "bearer",
+    "key": "",
+    "info": {
+      "id": "notion-local",
+      "name": "Notion (Local)",
+      "description": "Local Notion integration via MCPO"
+    }
+  }
+]
+```
+5.  Click **Save**.
+
+---
+
+## Creating an Internal Integration
+
+Required for **Method 2**, creating an internal integration within Notion ensures you have the necessary credentials and permission scopes readily available.
+
+### 1. Create Integration
+1.  Navigate to **[Notion My Integrations](https://www.notion.so/my-integrations)**.
 2.  Click the **+ New integration** button.
 3.  Fill in the required fields:
     *   **Integration Name:** Give it a recognizable name (e.g., "Open WebUI MCP").
@@ -41,7 +197,7 @@ You **must** select **Internal** for the integration type. Public integrations r
 
 ### 2. Configure Capabilities & Copy Secret
 Once saved, you will be directed to the configuration page.
-1.  **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for Open WebUI.
+1.  **Copy Secret:** Locate the **Internal Integration Secret** field. Click **Show** and copy this key. You will need it for MCPO configuration.
 2.  **Review Capabilities:** Ensure the following checkboxes are selected under the "Capabilities" section:
     *   ✅ **Read content**
     *   ✅ **Update content**
@@ -50,9 +206,9 @@ Once saved, you will be directed to the configuration page.
 3.  Click **Save changes** if you modified any capabilities.
 
 :::warning Security: Risk to Workspace Data
-While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk** to your data.
+While the Notion MCP server limits the scope of the API (e.g., databases cannot be deleted), exposing your workspace to LLMs carries a **non-zero risk**.
 
-**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content** in this step. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages.
+**Security-conscious users** can create a safer, **Read-Only** integration by unchecking **Update content** and **Insert content**. The AI will be able to search and answer questions based on your notes but will be physically unable to modify or create pages.
 :::
 
 :::danger Secret Safety
@@ -61,10 +217,10 @@ Your **Internal Integration Secret** allows access to your Notion data. Treat it
 
 ![Notion Capabilities Config: Shows the Internal Integration Secret revealed and the three content capability checkboxes selected.](/images/mcp-notion/notion-setup-step2.png)
 
-### 3. Grant Page Access
+### 3. Grant Page Access (Manual)
 
 :::danger Critical Step: Permissions
-By default, your new integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors.
+By default, your new internal integration has **zero access** to your workspace. It cannot see *any* pages until you explicitly invite it. If you skip this step, the AI will return "Object not found" errors.
 :::
 
 You can grant access centrally or on a per-page basis.
@@ -87,172 +243,11 @@ Still in the Notion Integration dashboard:
 
 ![Notion Page Connection: Shows a Notion page with the '...' menu open, the 'Connect' submenu active, and the integration being selected.](/images/mcp-notion/notion-setup-step4.png)
 
-## Configuration
+---
 
-There are two ways to connect Notion. We recommend **Streamable HTTP** for the easiest setup experience (OAuth), or **Local CLI** for advanced control using your integration token.
+## Configuration: Always On (Optional)
 
-The **Streamable HTTP** method is natively supported and recommended for most users for the easiest setup experience (OAuth).
-
-To run the server locally (using Docker or Node.js), you must use the **MCPO Bridge**.
-
-<Tabs>
-  <TabItem value="http" label="Method 1: Streamable HTTP (Recommended)" default>
-    This method connects directly to Notion's hosted MCP endpoint (`https://mcp.notion.com/mcp`). It utilizes standard OAuth and is **natively supported** by Open WebUI without extra containers.
-
-    ### Quick Setup via Import
-    You can automatically prefill the connection settings by importing the JSON configuration below.
-
-    1.  Navigate to **Admin Panel > Settings > External Tools**.
-    2.  Click the **+** (Plus) button to add a new tool.
-    3.  Click **Import** (top right of the modal).
-    4.  Paste the following JSON snippet:
-
-    ```json title="Notion Remote MCP Configuration"
-    [
-      {
-        "type": "mcp",
-        "url": "https://mcp.notion.com/mcp",
-        "spec_type": "url",
-        "spec": "",
-        "path": "openapi.json",
-        "auth_type": "oauth_2.1",
-        "key": "",
-        "info": {
-          "id": "ntn",
-          "name": "Notion",
-          "description": "A note-taking and collaboration platform that allows users to create, organize, and share notes, databases, and other content."
-        }
-      }
-    ]
-    ```
-
-    5.  **Enter Key:** Paste your **Internal Integration Secret** (starts with `secret_`) into the "Key" field.
-    6.  **Register:** Click the **Register Client** button (next to the Auth dropdown).
-    7.  Click **Save**.
-
-    ![Open WebUI Tool Config: Shows the External Tools modal with the JSON imported, Key pasted, and Register Client button highlighted.](/images/mcp-notion/notion-setup-step5.png)
-
-  </TabItem>
-
-  <TabItem value="mcpo" label="Method 2: Self-Hosted via MCPO (Advanced)">
-    Direct local execution (stdio) of MCP servers is not natively supported in Open WebUI. To run the Notion MCP server using `docker` or `npx` within your infrastructure, you must use **MCPO**.
-
-    MCPO acts as a bridge, running your local commands and exposing them to Open WebUI via a local HTTP endpoint.
-
-    ### Step 1: Deploy MCPO
-    Follow the installation instructions in the [MCPO Repository](https://github.com/open-webui/mcpo) to get it running (usually done via Docker).
-
-    ### Step 2: Configure MCPO
-    Configure your MCPO instance to run the Notion server using one of the runtimes below. Add the appropriate JSON block to your `mcpo-config.json` file.
-
-    <Tabs>
-      <TabItem value="npx" label="Node (npx)" default>
-        This configuration uses the official Node.js package.
-
-        ```json title="mcpo-config.json"
-        {
-          "mcpServers": {
-            "notion": {
-              "command": "npx",
-              "args": [
-                "-y",
-                "@notionhq/notion-mcp-server"
-              ],
-              "env": {
-                "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
-              }
-            }
-          }
-        }
-        ```
-      </TabItem>
-      <TabItem value="docker" label="Docker">
-        This configuration runs the server as an isolated container.
-
-        ```json title="mcpo-config.json"
-        {
-          "mcpServers": {
-            "notion": {
-              "command": "docker",
-              "args": [
-                "run",
-                "--rm",
-                "-i",
-                "-e",
-                "NOTION_TOKEN",
-                "mcp/notion"
-              ],
-              "env": {
-                "NOTION_TOKEN": "secret_YOUR_KEY_HERE"
-              }
-            }
-          }
-        }
-        ```
-      </TabItem>
-    </Tabs>
-
-    ### Step 3: Connect Open WebUI
-    Once MCPO is running and configured with Notion:
-
-    1.  Navigate to **Admin Panel > Settings > External Tools**.
-    2.  Click the **+** (Plus) button.
-    3.  Click **Import** (top right of the modal).
-    4.  Paste the following JSON snippet (update the URL with your MCPO address):
-
-    ```json title="MCPO Connection JSON"
-    [
-      {
-        "type": "openapi",
-        "url": "http://<YOUR_MCPO_IP>:<PORT>/notion",
-        "spec_type": "url",
-        "spec": "",
-        "path": "openapi.json",
-        "auth_type": "bearer",
-        "key": "",
-        "info": {
-          "id": "notion-local",
-          "name": "Notion (Local)",
-          "description": "Local Notion integration via MCPO"
-        }
-      }
-    ]
-    ```
-    5.  Click **Save**.
-  </TabItem>
-</Tabs>
-
-## Enabling the Tool
-
-After configuring the connection in the Admin Panel, you must enable the tool for the AI to use it.
-
-:::tip Initial Authentication
-If you are using **Method 1 (Streamable HTTP)**, you must perform the On-Demand step below at least once to trigger the OAuth flow. If using **Method 2 (MCPO)**, authentication is handled by the API key in your configuration.
-:::
-
-### Option 1: On-Demand (Per Chat)
-
-1.  Open a new chat.
-2.  Click the **+** (Plus) button in the chat input bar.
-3.  Navigate to **Integrations > Tools**.
-4.  Toggle the **Notion** switch to **ON**.
-
-![Chat Interface Toggle: Shows the chat input bar with the '+' menu open, 'Integrations' selected, and the 'Notion' tool toggled ON.](/images/mcp-notion/notion-setup-step6.png)
-
-5.  **Authorize:** (Method 1 Only) You will be redirected to a "Connect with Notion MCP" screen.
-    *   Ensure the correct **Workspace** (the one you configured in step 1) is selected in the dropdown.
-    *   Click **Continue**.
-
-:::note Security: Frequent Re-authentication
-For security reasons, Notion's OAuth session may expire after a period of inactivity or if you restart your Open WebUI instance. If this happens, you will see a `Failed to connect to MCP server 'ntn'` error. 
-
-This is **intended behavior** by Notion to keep your workspace secure. To refresh your session, revist steps 1-4 of this option to complete the "Connect with Notion MCP" authorization flow again, which will refresh your session.
-:::
-
-![Notion OAuth Screen: Shows the 'Connect with Notion MCP' authorization page with the workspace dropdown selected.](/images/mcp-notion/notion-setup-step7.png)
-
-### Option 2: Always On (Model Default)
-You can configure a specific model to have Notion access enabled by default for every conversation.
+By default, users must toggle the tool **ON** in the chat menu. You can configure a specific model to have Notion access enabled by default for every conversation.
 
 1.  Go to **Workspace > Models**.
 2.  Click the **pencil icon** to edit a model.
@@ -260,7 +255,7 @@ You can configure a specific model to have Notion access enabled by default for
 4.  Check the box for **Notion**.
 5.  Click **Save & Update**.
 
-## Best Practice: Create a Notion Agent
+## Building a Specialized Notion Agent (Optional)
 
 For the most reliable experience, we recommend creating a dedicated "Notion Assistant" model. This allows you to provide a specialized **System Prompt**, a helpful **Knowledge Base**, and quick-start **Prompt Suggestions** that teaches the model how to navigate Notion's structure.
 
@@ -335,7 +330,6 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to
 ```
 </details>
 
-
 7.  **Attach Knowledge Base:**
     *   In the **Knowledge** section, click **Select Knowledge**.
     *   In the modal that appears, find and select the **Notion MCP Docs** knowledge base you created in Step 1.
@@ -343,7 +337,7 @@ You are the Notion Workspace Manager, an intelligent agent connected directly to
 :::warning Performance Tuning
 While the knowledge base helps the model understand Notion's capabilities, injecting large amounts of documentation can sometimes interfere with tool calling on smaller models (overloading the context).
 
-If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above or use your own custom system prompt.
+If you notice the model failing to call tools correctly or hallucinating parameters, **detach the knowledge base** and rely solely on the System Prompt provided above.
 :::
 
 8.  **Add Prompt Suggestions:**
@@ -362,99 +356,15 @@ Under the **Prompts** section, click the **+** button to add a few helpful start
 
 ![Model Creation Screen: Shows the model settings with Name 'Notion Assistant', description, and the Notion System Prompt filled out.](/images/mcp-notion/notion-setup-step11.png)
 
-## Supported Tools & Usage
-
-Once enabled, the model will have access to a powerful suite of tools to manage your Notion workspace. The server automatically handles converting Notion's block-based structure into Markdown for the AI, and converts the AI's Markdown back into Notion blocks.
+## Supported Tools
 
 :::tip Workflow Best Practice
 LLMs cannot "browse" Notion like a human. For most actions, the model first needs to know the **Page ID or URL**. Always ask the model to **search** for a page first before asking it to read or modify it.
 :::
 
-## 🔎 Search & Retrieval  
+This integration supports a wide range of tools for searching, reading, creating, and updating Notion pages and databases.
 
-- **`notion-search`** – Full‑text / metadata search across Notion (and linked tools)  
-  - **Input:** query string (e.g., `ready for dev`)  
-  - **Returns:** list of object IDs + brief metadata  
-  - **Prompt example:** “Find all project pages that mention **‘ready for dev’**.”  
-  - **Note:** IDs returned here are required for almost every other command.  
-
-- **`notion-fetch`** *(aka `read-page`)* – Pull a page or database content by URL or ID  
-  - **Input:** page/database URL **or** ID  
-  - **Returns:** Markdown‑formatted content of the page/database  
-  - **Prompt example:** “What are the product requirements from this ticket `https://notion.so/page-url`?”  
-  - **Note:** Gives you a clean Markdown view, ready for further processing.  
-
-## 🛠️ Content Management  
-
-- **`notion-create-pages`** – Create a brand‑new page
-  - **Input:** parent page ID, title, property map, body (Markdown format)
-  - **Returns:** new page ID & URL
-  - **Prompt example:** “Create a meeting‑notes page for today’s stand‑up with action items.”
-  - **Key:** **Parent page ID is mandatory**.
-
-- **`notion-update-page`** – Patch a page’s **properties** (status, tags, dates, etc.)
-  - **Input:** page ID + property map
-  - **Returns:** updated page object
-  - **Prompt example:** “Change the status of this task from **‘In Progress’** to **‘Complete’**.”
-  - **Key:** Does **not** edit the page’s body blocks.
-
-- **`notion-append-block`** – Add a block (text, checklist, heading, etc.) to the end of a page
-  - **Input:** page ID + block payload (JSON format)
-  - **Returns:** updated page version
-  - **Prompt example:** “Add a checklist item to the bottom of the shopping‑list page.”
-
-- **`notion-move-pages`** – Move one or many pages/databases under a new parent
-  - **Input:** source page/database ID(s) + destination parent ID
-  - **Returns:** new parent relationship (page now lives under the target)
-  - **Prompt example:** “Move my weekly meeting‑notes page to the **‘Team Meetings’** page.”
-
-- **`notion-duplicate-page`** – Clone a page (asynchronous – returns a job ID)
-  - **Input:** source page ID (optional target parent)
-  - **Returns:** job ID → duplicated page ID once the job finishes
-  - **Prompt example:** “Duplicate my project‑template page for the new Q3 initiative.”
-
-## 📊 Database Management  
-
-- **`notion-create-database`** – Spin up a new database with a custom schema
-  - **Input:** parent page ID, title, property definitions (type, name, options)
-  - **Returns:** new database ID & URL
-  - **Prompt example:** “Create a database to track customer feedback with fields for **name**, **priority**, and **status**.”
-
-- **`notion-update-database`** – Alter a database’s schema (add/rename fields) or rename the DB itself
-  - **Input:** database ID + schema changes (add property, rename, etc.)
-  - **Returns:** updated database object
-  - **Prompt example:** “Add a **‘Status’** field to our project database to track completion.”
-
-## 💬 Collaboration & Workspace  
-
-- **`notion-create-comment`** – Post a comment on a page
-  - **Input:** page ID + comment text
-  - **Returns:** comment ID & timestamp
-  - **Prompt example:** “Leave a note on the quarterly review page about budget concerns.”
-
-- **`notion-get-comments`** – List every comment on a page (supports pagination)
-  - **Input:** page ID
-  - **Returns:** array of comment objects
-  - **Prompt example:** “List all comments on the project‑requirements section.”
-
-- **`notion-get-users`** – Fetch **all** workspace members
-  - **Input:** *(none)*
-  - **Returns:** array of user objects
-  - **Prompt example:** “Who are the members of this workspace?”
-
-- **`notion-get-user`** – Get a single user’s profile (by ID or email)
-  - **Input:** user ID or email address
-  - **Returns:** user object (name, avatar, email, etc.)
-  - **Prompt example:** “Look up the profile of the person assigned to this task.”
-
-- **`notion-get-teams`** – Retrieve all **teamspaces** (formerly “teams”) in the workspace
-  - **Input:** *(none)*
-  - **Returns:** array of team objects
-
-- **`notion-get-self`** – Information about the bot itself and the workspace it’s linked to
-  - **Input:** *(none)*
-  - **Returns:** bot metadata + workspace metadata (ID, name, domain, etc.)
-  - **Prompt example:** “Which Notion workspace am I currently connected to?”
+For a complete list of available tools, their descriptions, and specific usage examples, please refer to the **[official Notion MCP documentation](https://developers.notion.com/docs/mcp-supported-tools)**.
 
 ## Rate Limits
 Standard [API request limits](https://developers.notion.com/reference/request-limits) apply to your use of Notion MCP, totaled across all tool calls.
@@ -468,7 +378,9 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa
 
 ## Troubleshooting
 
-### Error: `Failed to connect to MCP server 'ntn'`
+### Connection Errors
+
+#### `Failed to connect to MCP server 'ntn'`
 
 ![MCP Connection Error: Shows a red error message in the chat 'Failed to connect to MCP server 'ntn'.](/images/mcp-notion/notion-setup-step12.png)
 
@@ -480,27 +392,26 @@ If you encounter rate limit errors, prompt your model to reduce the number of pa
     4.  This will trigger the redirect to Notion's authorization page to complete the "Connect with Notion MCP" authorization flow again.
     5.  Once authorized successfully, the connection will work across all chats again, including for models with the tool enabled by default.
 
-### Error: `OAuth callback failed: mismatching_state`
-
+#### `OAuth callback failed: mismatching_state`
 ![OAuth Error Toast: Shows the red error notification 'OAuth callback failed: mismatching_state: CSRF Warning! State not equal in request and response'.](/images/mcp-notion/notion-setup-step13.png)
 
-If you receive this red error toast when registering the client or connecting via the tool toggle, it is likely due to a URL mismatch.
-
 *   **Cause:** You are likely accessing Open WebUI via `localhost` (e.g., `http://localhost:3000`), but your instance is configured with a public domain via the `WEBUI_URL` environment variable (e.g., `https://chat.mydomain.com`). The OAuth session state created on `localhost` is lost when the callback redirects to your public domain.
 *   **Fix:** Access your Open WebUI instance using the **exact URL** defined in `WEBUI_URL` (your public domain) and perform the setup again. **Do not use `localhost` for OAuth setups if a domain is configured.**
 
-### Error: `Object not found`
+### Usage Errors
+
+#### `Object not found`
 *   **Cause:** The Integration Token is valid, but the specific page has not been shared with the integration.
 *   **Fix:** In Notion, go to your Integration settings > **Access** tab and ensure the page is checked, or visit the page directly and check the **Connections** menu to ensure your integration is listed and selected.
 
-### Error: `Tool execution failed` (Local Method)
+#### `Tool execution failed` (Local Method)
 *   **Cause:** Open WebUI is unable to execute the local command (npx/docker) because it is missing from the container, or the configuration is incorrect.
 *   **Fix:** Native local execution is not supported. Ensure you are using **MCPO** (Method 2) to bridge these commands, rather than entering them directly into Open WebUI's config, or switch to **Method 1 (Streamable HTTP)** in the Configuration section above. This runs on Notion's servers and requires no local dependencies.
 
-### Error: `missing_property` when creating a page
+#### `missing_property` when creating a page
 *   **Cause:** The model is trying to create a page without specifying a **Parent ID**. Notion requires every page to exist inside another page or database.
 *   **Fix:** Instruct the model in your prompt: *"Search for my 'Notes' page first, get its ID, and create the new page inside there."*
 
-### Error: `RateLimitedError` (429)
+#### `RateLimitedError` (429)
 *   **Cause:** You have exceeded Notion's API limits (approx. 3 requests/second).
 *   **Fix:** Ask the model to perform actions sequentially rather than all at once (e.g., "Search for X, then wait, then search for Y").