Open WebUI

Open WebUI supports pluggable content extraction backends. Xberg 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 Xberg’s API endpoint.
3. Xberg extracts the content — running OCR where needed and returns Markdown.
4. Open WebUI stores the Markdown in its vector database for retrieval-augmented generation.

Xberg supports 101 file formats and requires no GPU.

Prerequisites

• Docker and Docker Compose (v2)
• Open WebUI running or ready to deploy
• No GPU required — Xberg runs entirely on CPU

Setup with Docker Compose

This is the fastest way to get both services running together.

docker-compose.yaml

services:
  xberg:
    image: ghcr.io/xberg-io/xberg:latest-core
    ports:
      - "8000:8000"
    command: ["serve", "--host", "0.0.0.0", "--port", "8000"]
    volumes:
      - xberg-cache:/app/.xberg
    healthcheck:
      test: ["CMD", "xberg", "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://xberg:8000"
    depends_on:
      xberg:
        condition: service_healthy

volumes:
  xberg-cache:

Start both services in detached mode:

docker compose up -d

Open http://localhost:3000, create an account, and upload a document. The extracted text will appear in the chat context.

Cache volume

The xberg-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).

Already running Open WebUI?

Start Xberg separately, then point Open WebUI to that Xberg URL.

Docker

docker run -d \
  --name xberg \
  -p 8000:8000 \
  -v xberg-cache:/app/.xberg \
  ghcr.io/xberg-io/xberg:latest-core \
  serve --host 0.0.0.0 --port 8000

CLI (Homebrew / Cargo)

xberg serve --host 0.0.0.0 --port 8000

Then configure Open WebUI using one of the two engine modes below.

Choosing an engine mode

Xberg 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:

environment:
  CONTENT_EXTRACTION_ENGINE: "docling"
  DOCLING_SERVER_URL: "http://xberg:8000"

Or via the Admin UI: Settings → Documents → Content Extraction Engine → select Docling → set server URL to http://xberg:8000.

External

Set these environment variables on the Open WebUI container:

environment:
  CONTENT_EXTRACTION_ENGINE: "external"
  EXTERNAL_DOCUMENT_LOADER_URL: "http://xberg:8000"

Or via the Admin UI: Settings → Documents → Content Extraction Engine → select External → set URL to http://xberg:8000.

Tip

If Xberg runs on a different host or port, replace http://xberg:8000 with the actual address. Inside Docker Compose, use the service name (xberg). Outside Docker, use the host IP or localhost.

Verify it works

Test the endpoints directly before debugging through Open WebUI.

Docling endpoint

curl -s -F "files=@invoice.pdf" http://localhost:8000/v1/convert/file | jq .

Expected response

{
  "document": {
    "md_content": "# Invoice\n\nDate: 2026-01-15\n..."
  },
  "status": "success"
}

External endpoint

curl -s -X PUT \
  -H "Content-Type: application/pdf" \
  -H "X-Filename: invoice.pdf" \
  --data-binary @invoice.pdf \
  http://localhost:8000/process | jq .

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.

Large or slow documents

Both endpoints enforce extraction_timeout_secs (default 600 seconds / 10 minutes) and return HTTP 500 if a document doesn’t finish extracting in time. Documents that lean on slow paths — VLM-based OCR, large scanned PDFs — can exceed the default on constrained hardware. Raise the limit in xberg.toml next to the compose file (auto-discovered on serve startup):

xberg.toml

extraction_timeout_secs = 1800

TOML has no null literal, so a TOML config can only raise the limit, not disable it; use a YAML or JSON config with extraction_timeout_secs: null (YAML) or "extraction_timeout_secs": null (JSON) to turn enforcement off entirely. For the Docker Compose setup above, mount the file alongside the xberg-cache volume and pass --config /app/xberg.toml in command (or rely on auto-discovery if the file lives in the container’s working directory).

Next steps

• Docker deployment guide — image variants, volumes, security hardening
• API server reference — all endpoints and configuration options
• OCR guide — language packs, engine selection, tuning
• Format support — full list of supported file types