Open WebUI: Improve documentation

Author: amotl

application/open-webui/README.md

@@ -2,63 +2,100 @@
 
 ## About
 
-A complete end-to-end rig including CrateDB, CrateDB MCPO, and Open WebUI. 
+A complete end-to-end rig including CrateDB, CrateDB MCPO, and Open WebUI,
+including a touch of integration tests on CI/GHA.
+
+## Introduction
 
 [Open WebUI] is an extensible, feature-rich, and user-friendly self-hosted AI
 platform designed to operate entirely offline. It supports various LLM runners
 like Ollama and OpenAI-compatible APIs, with built-in inference engine for RAG,
 making it a powerful AI deployment solution.
 
-CrateDB MCPO is a wrapper around CrateDB MCP, publishing the exposed tools via
-OpenAPI, to connect it to Open WebUI.
-
-## What's inside
+CrateDB MCPO is an adapter wrapper around the [CrateDB MCP] server. Because
+Open WebUI uses [OpenAPI Tool Servers] to integrate external tooling and data
+sources into LLM agents and workflows, standard MCP servers need to adapt to
+how [Open WebUI MCP Support] works.
 
-- `.env`: The dotenv file defines `OPENAI_API_KEY` for `compose.yml` and `OPEN_WEBUI_URL` for `setup.sh`.
-- `compose.yml`: The service composition file defines three services: CrateDB, CrateDB MCPO, and Open WebUI.
-  Use it with `docker compose` or `podman compose`.
-- `setup.Dockerfile`: Container runtime definition for `setup.sh`, including all requirements.
-- `setup.sh`: Program that configures Open WebUI via HTTP API.
-- `tool-servers.json`: JSON snippet for configuring the CrateDB MCPO server through `/api/v1/configs/tool_servers`.
+## Usage
 
-## Operate
+### Start services
 
 Configure the API key for OpenAI as environment variable, or define it within
 the `.env` file.
 ```shell
-export OPENAI_API_KEY=<your_openapi_key>
+export OPENAI_API_KEY=<your_openai_api_key>
 ```
 
-Spin up the software stack.
+Spin up the software stack. On the first occasion, it will take a while
+to download the OCI images and let Open WebUI do its thing on its first
+boot.
 ```shell
-docker compose up -d
+docker compose up
 ```
 
-## Usage
+### User interface
 
-You can access the services and their resources on those URLs.
+You can access the service's resources on those URLs.
 
 - CrateDB: http://localhost:4200/
-- CrateDB MCPO: http://localhost:5200/docs, http://localhost:5200/openapi.json
-- Open WebUI: http://localhost:6200/, http://localhost:6200/docs
+- Open WebUI: http://localhost:6200/
+
+Explore the APIs here.
+
+- CrateDB MCPO: 
+  - Swagger: http://localhost:5200/docs
+  - OpenAPI: http://localhost:5200/openapi.json
+- Open WebUI: 
+  - Swagger: http://localhost:6200/docs
+  - OpenAPI: http://localhost:6200/openapi.json
 
-## Configure
+### Configure
 
 To make the ensemble work well, you need to configure a few bits on the Open WebUI
-user interface after ramping up the rig.
+user interface.
+
+- Make sure to enable the "CrateDB" tool. The toggle switch is located within the
+  flyout menu on the left side of the query prompt, which can be opened using the
+  `More (+)` button.
+
+- In the "Chat Controls" flyout widget, located in the top right corner of the page,
+  - make sure to enable `Function Calling: Native`, and
+  - dial down to `Temperature: 0.0`.
+
+### Example questions
 
-- Make sure to enable the "CrateDB" tool on the left side of the query prompt,
-  behind the "More (`+`)" button.
-- Make sure to enable "Function Calling: Native" within the flyout widget about
-  "Chat Controls", to be opened in the top right corner of the screen.
-- If you like, you can dial down to "Temperature: 0.5".
+Enjoy conversations with CrateDB (talk to your data) and its documentation
+(talk to your knowledgebase).
 
-## Example questions
+- Text-to-SQL: _What is the average value for sensor 1?_
+- Knowledgebase: _How do I use CrateDB with SQLAlchemy?_
 
-Enjoy conversations with CrateDB and its documentation.
+### Stop services
+Tear down services.
+```shell
+docker compose down
+```
+Delete volumes.
+```shell
+docker volume rm open-webui_open-webui
+```
+```shell
+docker volume rm open-webui_cratedb
+```
+
+## What's inside
+
+- `.env`: The dotenv file defines `OPENAI_API_KEY` for `compose.yml` and `OPEN_WEBUI_URL` for `setup.sh`.
+- `compose.yml`: The service composition file defines three services: CrateDB, CrateDB MCPO, and Open WebUI.
+  Use it with Docker or Podman.
+- `setup.Dockerfile`: Container runtime definition for `setup.sh`, including all requirements.
+- `setup.sh`: Program that configures Open WebUI via HTTP API.
+- `tool-servers.json`: JSON snippet for configuring the CrateDB MCPO server through `/api/v1/configs/tool_servers`.
 
-- Text-to-SQL: What is the average value for sensor 1?
-- Knowledgebase: How do I use CrateDB with SQLAlchemy?
 
 
+[CrateDB MCP]: https://cratedb.com/docs/guide/integrate/mcp/cratedb-mcp.html
+[OpenAPI Tool Servers]: https://docs.openwebui.com/openapi-servers/
 [Open WebUI]: https://docs.openwebui.com/
+[Open WebUI MCP Support]: https://docs.openwebui.com/openapi-servers/mcp/