Nomad changes

docs/integrations/openwebui.md

@@ -0,0 +1,168 @@
+# Open WebUI
+
+![Kreuzberg](https://img.shields.io/badge/kreuzberg-v4.7.0+-blue)
+
+Open WebUI supports pluggable content extraction backends. Kreuzberg implements two of those backend APIs — the **docling-serve** endpoint and the **external document loader** endpoint, so it works as a drop-in replacement without patching Open WebUI.
+
+## How it works
+
+1. A user uploads a document (PDF, DOCX, image, etc.) in Open WebUI.
+2. Open WebUI sends the file to Kreuzberg's API endpoint.
+3. Kreuzberg extracts the content — running OCR where needed and returns Markdown.
+4. Open WebUI stores the Markdown in its vector database for retrieval-augmented generation.
+
+Kreuzberg supports [90+ file formats](../reference/formats.md) and requires no GPU.
+
+## Prerequisites
+
+- Docker and Docker Compose (v2)
+- Open WebUI running or ready to deploy
+- No GPU required — Kreuzberg runs entirely on CPU
+
+## Setup with Docker Compose
+
+This is the fastest way to get both services running together.
+
+```yaml title="docker-compose.yaml"
+services:
+  kreuzberg:
+    image: ghcr.io/kreuzberg-dev/kreuzberg:latest-core
+    ports:
+      - "8000:8000"
+    command: ["serve", "--host", "0.0.0.0", "--port", "8000"]
+    volumes:
+      - kreuzberg-cache:/app/.kreuzberg
+    healthcheck:
+      test: ["CMD", "kreuzberg", "version"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+
+  open-webui:
+    image: ghcr.io/open-webui/open-webui:main
+    ports:
+      - "3000:8080"
+    environment:
+      CONTENT_EXTRACTION_ENGINE: "docling"
+      DOCLING_SERVER_URL: "http://kreuzberg:8000"
+    depends_on:
+      kreuzberg:
+        condition: service_healthy
+
+volumes:
+  kreuzberg-cache:
+```
+
+Start both services in detached mode:
+
+```bash
+docker compose up -d
+```
+
+Open `http://localhost:3000`, create an account, and upload a document. The extracted text will appear in the chat context.
+
+!!! Note "Cache volume" The `kreuzberg-cache` volume persists OCR models and embedding weights across restarts. Without it, models re-download on every container restart (~90 MB–1.2 GB depending on configuration).
+
+!!! Info "Already running Open WebUI?" Start Kreuzberg separately, then point Open WebUI to that Kreuzberg URL.
+
+=== "Docker"
+
+    ```bash
+    docker run -d \
+      --name kreuzberg \
+      -p 8000:8000 \
+      -v kreuzberg-cache:/app/.kreuzberg \
+      ghcr.io/kreuzberg-dev/kreuzberg:latest-core \
+      serve --host 0.0.0.0 --port 8000
+    ```
+
+=== "CLI (Homebrew / Cargo)"
+
+    ```bash
+    kreuzberg serve --host 0.0.0.0 --port 8000
+    ```
+
+Then configure Open WebUI using one of the two engine modes below.
+
+## Choosing an engine mode
+
+Kreuzberg exposes two Open WebUI–compatible APIs. Both return the same extracted content. So pick whichever fits your setup.
+
+|                    | **Docling** (recommended) | **External**                   |
+| ------------------ | ------------------------- | ------------------------------ |
+| **Endpoint**       | `POST /v1/convert/file`   | `PUT /process`                 |
+| **Engine setting** | `docling`                 | `external`                     |
+| **URL variable**   | `DOCLING_SERVER_URL`      | `EXTERNAL_DOCUMENT_LOADER_URL` |
+
+=== "Docling (recommended)"
+
+    Set these environment variables on the Open WebUI container:
+
+    ```yaml
+    environment:
+      CONTENT_EXTRACTION_ENGINE: "docling"
+      DOCLING_SERVER_URL: "http://kreuzberg:8000"
+    ```
+
+    Or via the Admin UI: **Settings → Documents → Content Extraction Engine** → select **Docling** → set server URL to `http://kreuzberg:8000`.
+
+=== "External"
+
+    Set these environment variables on the Open WebUI container:
+
+    ```yaml
+    environment:
+      CONTENT_EXTRACTION_ENGINE: "external"
+      EXTERNAL_DOCUMENT_LOADER_URL: "http://kreuzberg:8000"
+    ```
+
+    Or via the Admin UI: **Settings → Documents → Content Extraction Engine** → select **External** → set URL to `http://kreuzberg:8000`.
+
+!!! Tip If Kreuzberg runs on a different host or port, replace `http://kreuzberg:8000` with the actual address. Inside Docker Compose, use the service name (`kreuzberg`). Outside Docker, use the host IP or `localhost`.
+
+## Verify it works
+
+Test the endpoints directly before debugging through Open WebUI.
+
+=== "Docling endpoint"
+
+    ```bash
+    curl -s -F "files=@invoice.pdf" http://localhost:8000/v1/convert/file | jq .
+    ```
+
+    ```json title="Expected response"
+    {
+      "document": {
+        "md_content": "# Invoice\n\nDate: 2026-01-15\n..."
+      },
+      "status": "success"
+    }
+    ```
+
+=== "External endpoint"
+
+    ```bash
+    curl -s -X PUT \
+      -H "Content-Type: application/pdf" \
+      -H "X-Filename: invoice.pdf" \
+      --data-binary @invoice.pdf \
+      http://localhost:8000/process | jq .
+    ```
+
+    ```json title="Expected response"
+    {
+      "page_content": "# Invoice\n\nDate: 2026-01-15\n...",
+      "metadata": {
+        "source": "invoice.pdf"
+      }
+    }
+    ```
+
+If the endpoint returns extracted text, the integration is working. Upload a document through Open WebUI to confirm end-to-end.
+
+## Next steps
+
+- [Docker deployment guide](../guides/docker.md) — image variants, volumes, security hardening
+- [API server reference](../guides/api-server.md) — all endpoints and configuration options
+- [OCR guide](../guides/ocr.md) — language packs, engine selection, tuning
+- [Format support](../reference/formats.md) — full list of supported file types