diff --git a/README.md b/README.md index f1e1f3f..fd09543 100644 --- a/README.md +++ b/README.md @@ -136,6 +136,147 @@ Both scripts are **idempotent** — safe to re-run for updates. Config files are ./kiwix_download.sh ``` +6. **Configure Open WebUI** (see next section for exact clicks) + +--- + +## Open WebUI Admin Settings — Click-by-Click Setup + +After the stack is running, open `http://:3000`, create your admin account, then go to +**your avatar (top-right)** → **Admin Panel** → **Settings** tab at the top. + +You'll see the sidebar: General, Connections, Models, Evaluations, Integrations, Documents, +Web Search, Code Execution, Interface, Audio, Images, Pipelines, Database. + +Here's what to configure in each: + +### Connections + +This is where Open WebUI talks to Ollama and the RAG server. + +1. Click **Connections** in the sidebar +2. Under **Ollama API**, verify the URL is `http://ollama:11434` + - Click the refresh icon — it should show "Connected" and list your models +3. Under **OpenAI API**, verify: + - URL: `http://rag-server:8001/v1` + - API Key: `local-rag` + - This is your RAG server posing as an OpenAI-compatible API +4. Click **Save** + +> These are pre-configured by the setup script's environment variables. You usually +> don't need to change anything here — just verify the green "Connected" status. + +### Models + +1. Click **Models** in the sidebar +2. You should see your pulled Ollama models listed (e.g., `qwen3.5:4b`) +3. Click a model to set its **system prompt**, **temperature**, etc. +4. To set a **default model** for new chats: click the model → toggle **Default** + +### Integrations (MCP Tool Server) + +This is where you connect the MCP server so Open WebUI models can use tools +(search files, run bash, query git, etc.). + +1. Click **Integrations** in the sidebar +2. Under **Tool Servers** section, click **+ Add Connection** +3. Enter: + - **URL:** `http://mcp-server:8002/sse` + - (Use the Docker container name, not your LAN IP — they're on the same Docker network) +4. Click **Save** / **Verify** +5. You should see your MCP tools listed (file_search, bash_exec, git_status, etc.) + +Once connected, any model in Open WebUI can use these tools during chat. You'll see +tool calls appear inline when the model decides to search code, read files, etc. + +> **Note:** This is separate from `claude mcp add local http://:8002/sse` which +> connects Claude Code (the CLI). Both can connect to the same MCP server simultaneously. + +### Documents + +Controls how Open WebUI's built-in Knowledge Collections work (the `#` tag system). + +1. Click **Documents** in the sidebar +2. **Top K:** `6` (number of chunks retrieved per query — default is fine) +3. **Chunk Size:** `1500` (characters per chunk) +4. **Chunk Overlap:** `200` +5. **RAG Template:** Leave default unless you want custom formatting + +> This is for Open WebUI's own Knowledge Collections, NOT the code-aware RAG server +> (which runs separately and is always active). + +### Web Search + +1. Click **Web Search** in the sidebar +2. **Enable Web Search:** Toggle ON +3. **Engine:** Select `duckduckgo` (no API key needed) or `searxng` + - If using SearXNG (self-hosted): URL is `http://searxng:8080` +4. Click **Save** + +Once enabled, models can search the web during chat when you click the globe icon +or when the model decides it needs current information. + +### Images (ComfyUI integration) + +This is how "generate an image of..." works from chat. + +1. Click **Images** in the sidebar +2. **Enable Image Generation:** Toggle ON +3. **Engine:** Select `ComfyUI` +4. **ComfyUI Base URL:** `http://comfyui:8188` + - (These should already be filled in from the env vars set during setup) +5. Click the **checkmark/verify** button — should show "Connected" +6. **Import Workflow:** Click and upload your `workflow_api.json` + - If you don't have one yet, see [ComfyUI workflow setup](#setup-comfyui--open-webui-recommended) +7. **Map nodes:** After importing, map the **prompt node** to the CLIPTextEncode + node (or whichever node takes the text prompt) +8. Click **Save** + +> **No workflow yet?** You need to first open ComfyUI at `http://:8188`, +> build or load a workflow, enable Dev Mode (gear icon), and click +> "Save (API Format)" to get the `workflow_api.json` file. See the +> [Image Generation](#image-generation-from-open-webui) section below. + +### Interface + +1. Click **Interface** in the sidebar +2. **Default System Prompt:** Set a global system prompt for all chats (optional) + - Example: "You are a helpful coding assistant. Be concise." +3. **Chat Bubble UI:** Toggle to switch between chat bubbles and flat messages +4. **Rich Text Input:** Toggle ON for markdown formatting in the input box + +### Audio + +1. Click **Audio** in the sidebar +2. **Speech-to-Text (STT):** Select engine (browser default works, or Whisper) +3. **Text-to-Speech (TTS):** Select engine (browser default, or configure OpenAI-compatible) +4. These are optional — skip if you don't need voice + +### Pipelines + +Advanced: for custom middleware between the user and the model. Skip unless you're +building custom processing pipelines. + +### Database + +Shows database stats. No configuration needed. + +--- + +### Recommended Open WebUI Functions (one-time install) + +These are community add-ons that improve the chat experience. Install from +**Admin Panel** → **Functions** tab (at the top, next to Settings) → **+** button +→ paste the URL → **Import**. + +| Function | URL | What it does | +|----------|-----|-------------| +| Context Tracker | `https://openwebui.com/f/centrisic/context_tracker` | Shows tokens used vs available, progress bar, context % remaining | +| Context Compaction | `https://openwebui.com/f/projectmoon/checkpoint_summarization_filter` | Auto-summarizes old messages when context fills up (like Claude does) | +| Auto Memory | Search "Auto Memory" in Discover | Automatically stores relevant info as persistent memories across chats | + +After importing each function, toggle it **ON** in the Functions list. + --- ## Querying Your Codebase from Open WebUI