GUIDE.md

EdukaAI OpenWebUI Plugin - Beginner's Guide

🎯 Goal: Export your best OpenWebUI conversations to EdukaAI for LLM fine-tuning with just one click.

---

🚀 Getting OpenWebUI Running (First-Time Setup)

New to OpenWebUI? Follow these steps to get it up and running first.

Option 1: Docker Standalone (No Ollama - API Mode Only)

Use this if you:

• Don't have Ollama installed
• Plan to use OpenAI, Anthropic, or other cloud APIs
• Want to test OpenWebUI without local models

This runs OpenWebUI without any local LLM connection. You'll configure cloud API providers separately in the UI settings.

Step 1: Install Docker

1. Windows/Mac: Download Docker Desktop

   • Run the installer
   • Restart your computer if prompted
   • Open Docker Desktop and wait for it to start

2. Linux: Run in terminal:

   # Ubuntu/Debian
   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER
   newgrp docker

Step 2: Run OpenWebUI with Docker

Open your terminal/command prompt and run:

# Basic installation (works with Ollama locally)
docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

Step 3: Access OpenWebUI

1. Wait 30-60 seconds for the container to start
2. Open your browser to: http://localhost:3000
3. Create your first admin account (this becomes the admin user)
4. You're in! 🎉

Option 2: Docker with Ollama (Most Common Setup)

Already have Ollama running on localhost:11434? This section is for you!

This is the most common scenario - you've been using Ollama in your terminal, and now you want to add OpenWebUI's nice interface on top of it.

Step 1: Verify Ollama is Running

First, make sure Ollama is actually running:

# Check if Ollama responds
curl http://localhost:11434/api/tags

# Or just check if the process is running
ollama list

You should see a list of your downloaded models. If not, start Ollama:

ollama serve

Step 2: Choose Your Platform

The connection method differs by operating system:

---

🖥️ Windows & Mac (Easiest)

Docker Desktop automatically handles localhost access via host.docker.internal:

# Run with Ollama connection
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

---

🐧 Linux (Requires Extra Step)

On Linux, host.docker.internal doesn't work by default. You have two options:

Option A: Use host network mode (Simplest)

docker run -d --network=host \
  -e OLLAMA_BASE_URL=http://localhost:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Access at: http://localhost:8080 (not 3000!)

Option B: Find your host IP (More secure)

# Find your host's IP address
ip addr show | grep "inet " | head -1
# Usually something like: 192.168.1.100

# Use that IP in the connection string
docker run -d -p 3000:8080 \
  -e OLLAMA_BASE_URL=http://192.168.1.100:11434 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

---

🐳 Docker Compose (Recommended for Linux)

Create a docker-compose.yml file:

version: '3.8'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    restart: always
    extra_hosts:
      - "host.docker.internal:host-gateway"

volumes:
  open-webui:

Run it:

docker-compose up -d

Step 3: Verify the Connection

1. Open http://localhost:3000
2. Create/login to your account
3. Look at the top-left dropdown (model selector)
4. You should see your Ollama models listed!

Common Connection Issues

❌ "Connection refused" or "Cannot connect to Ollama"

Solutions:

1. Check Ollama is running:

   curl http://localhost:11434/api/tags

2. For Linux - Ollama might not be listening on all interfaces:

   # Check Ollama's bind address
   sudo netstat -tlnp | grep 11434
   # If it shows 127.0.0.1:11434, that's good
   # If no output, Ollama isn't running

3. Make Ollama listen on all interfaces (Linux only):

   # Stop Ollama
   sudo systemctl stop ollama
   
   # Start with explicit host binding
   OLLAMA_HOST=0.0.0.0:11434 ollama serve
   
   # Or edit the systemd service:
   sudo systemctl edit ollama
   # Add:
   # [Service]
   # Environment="OLLAMA_HOST=0.0.0.0:11434"

4. Check firewall (Linux):

   sudo ufw allow 11434/tcp
   # or
   sudo iptables -A INPUT -p tcp --dport 11434 -j ACCEPT

❌ "No models found"

You need to download models first:

ollama pull llama3.2
ollama pull mistral
# etc.

❌ "Connection timeout"

If using IP address method on Linux, the IP might have changed:

1. Get your current IP: ip addr show | grep inet
2. Recreate the container with the new IP
3. Or use host network mode instead

Alternative: No Ollama Connection (API-Only Mode)

Don't want to use Ollama? You can use OpenWebUI with OpenAI, Anthropic, or other APIs:

# Basic run without Ollama
docker run -d -p 3000:8080 \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

Then configure API connections in Settings → Connections.

---

Option 3: Python/Conda Installation

For developers who prefer running it directly:

# Install with pip
pip install open-webui

# Start the server
open-webui serve

# Or with custom port
open-webui serve --port 3000

Requirements:

• Python 3.11 or higher
• 4GB RAM minimum (8GB recommended)

Option 4: Cloud/Remote Installation

Want to run it on a server or VPS?

# On your server
docker run -d -p 3000:8080 -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main

# Access via server IP: http://your-server-ip:3000

Important for remote access:

• Set up SSL/HTTPS for security
• Configure authentication properly
• Check firewall rules for port 3000

Verifying Installation

✅ OpenWebUI is working if:

• You can access http://localhost:3000
• You see the login/create account page
• After logging in, you see the chat interface

Need Help?

• Official OpenWebUI Docs
• OpenWebUI Discord
• GitHub Issues

---

📋 What You'll Need

Before we install the plugin, make sure you have:

1. OpenWebUI installed and running (version 0.3.0 or higher)

   • Access it at http://localhost:3000 (or your custom URL)
   • Not installed yet? See the section above ☝️

2. EdukaAI installed and running (version 0.2.1 or higher)

   • Should be running at http://localhost:3030
   • Not installed yet? Install EdukaAI first

⚠️ Docker Users: If OpenWebUI runs in Docker, it can't use localhost:3030 to reach EdukaAI. The plugin is pre-configured with http://host.docker.internal:3030 which works for macOS/Windows. Linux users may need to use their host IP instead - we'll cover this in the configuration step.

---

🚀 Installation Options

We offer 3 ways to install the plugin. Choose the one that works best for you:

Method	Difficulty	Best For
Method 1: GitHub URL ⭐	⭐ Easy	Most users - direct from GitHub
Method 2: Community Hub	⭐ Easy	If listed on openwebui.com
Method 3: Manual Install	⭐⭐ Medium	Troubleshooting or offline use

---

⭐ Method 1: Install from GitHub URL (Recommended)

This is the easiest and fastest way to install the plugin directly from our GitHub repository.

Step 1: Open Your OpenWebUI

1. Navigate to your OpenWebUI instance

   • Usually: http://localhost:3000
   • Or your custom domain

2. Login with your admin/user account

Step 2: Access the Functions Section

1. Look at the left sidebar
2. Click on "Workspace" (🏠 icon)
3. In the submenu, click "Functions"

You should see a page that says "Functions" at the top with a list (possibly empty) below.

Step 3: Create a New Function

1. Click the "+" button or "Create Function" button (usually in the top-right)
2. A dialog will appear asking for the function details

Step 4: Import from URL

1. Look for the "Import from URL" option
2. Paste this URL:

   https://github.com/ElGap/edukaai-openwebui
   

   Or the raw file URL:

   https://raw.githubusercontent.com/ElGap/edukaai-openwebui/main/edukaai_openwebui.py
   

3. Click "Import" or "Load"

💡 Tip: If the import button is greyed out, try the raw GitHub URL instead.

Step 5: Review the Code (Security Check)

⚠️ Important: OpenWebUI will show you the Python code before saving. This is a security feature!

Take a quick look to verify it says:

• title: EdukaAI Export
• author: EdukaAI
• The code looks legitimate (no suspicious network calls to unknown servers)

Click "Save" when you're ready.

Step 6: Enable the Plugin

1. You'll be back at the Functions list
2. Find "EdukaAI Export" in the list
3. Toggle the switch to "ON" (it should turn blue/green)

Step 7: Configure the Plugin (Important!)

1. Click the ⚙️ gear icon next to the toggle

2. A settings panel will open with these options:

   Setting	Default Value	What to Enter
   EDUKAAI_ENDPOINT	http://host.docker.internal:3030	Docker + macOS/Windows: Keep default ✅ Docker + Linux: Use your host IP (e.g., http://172.17.0.1:3030) Native install: Use http://localhost:3030
   EDUKAAI_DATASET_ID	(empty)	Optional - specific dataset ID to save to
   DEFAULT_CATEGORY	general	Default category (coding, explanation, writing, etc.)
   DEFAULT_QUALITY	4	Default quality rating 1-5 (4 = Very Good)
   AUTO_APPROVE	false	Set to true to auto-approve in EdukaAI

3. Click "Save" when done

💡 Tip: Find your Linux host IP with: ip addr show docker0 | grep inet

🎉 Congratulations! The plugin is now installed and ready to use.

Skip to Using the Plugin

---

🌐 Method 2: Install from OpenWebUI Community Hub

If the plugin is listed on the OpenWebUI Community, you can install it directly from there.

Step 1: Visit the Community Hub

1. Go to openwebui.com/functions
2. Search for "EdukaAI" or "edukaai-export"

Step 2: Find the Plugin

1. Click on the "EdukaAI Export" function
2. Click the "Get" or "Install" button

Step 3: Connect to Your Instance

1. A dialog will appear
2. Enter your OpenWebUI URL:
   • Default: http://localhost:3000
   • Or your custom URL
3. Click "Import to Open WebUI"

Step 4: Review and Save

You'll be redirected to your OpenWebUI instance:

1. Review the code (security check)
2. Click "Save"
3. Enable the toggle
4. Configure settings (see Step 7 in Method 1)

🎉 Done!

Skip to Using the Plugin

---

📝 Method 3: Manual Installation (Copy & Paste)

Use this method if the URL import isn't working or you're offline.

Step 1: Download the Plugin File

Option A: From GitHub Website

1. Visit: https://github.com/ElGap/edukaai-openwebui
2. Click on edukaai_openwebui.py
3. Click the "Raw" button
4. Select all the text (Ctrl+A / Cmd+A)
5. Copy it (Ctrl+C / Cmd+C)

Option B: Using curl (Command Line)

curl -o edukaai_openwebui.py https://raw.githubusercontent.com/ElGap/edukaai-openwebui/main/edukaai_openwebui.py

Step 2: Create Function in OpenWebUI

1. Go to OpenWebUI → Workspace → Functions
2. Click "Create Function"
3. A code editor will appear

Step 3: Paste the Code

1. Clear the editor (select all, delete)
2. Paste the copied code (Ctrl+V / Cmd+V)
3. You should see the complete plugin code

Step 4: Save and Enable

1. Give it a name: "EdukaAI Export"
2. Click "Save"
3. Toggle it ON
4. Configure settings (see Step 7 in Method 1)

🎉 Installation complete!

---

🎯 Using the Plugin

Now that the plugin is installed, let's export your first conversation!

Step 1: Start a Conversation

1. Go to OpenWebUI's main chat page
2. Select any model
3. Have a conversation (ask something, get a response)

Step 2: Export a Message Pair

1. Find a good assistant response you want to save
2. Look under the message for action buttons
3. Click the 📚 Export to EdukaAI button
   • It looks like a book or export icon
   • If you don't see it, make sure the plugin is enabled
4. The export happens immediately using your pre-configured settings
5. You'll see a toast notification:
   • Green: ✅ Exported to EdukaAI! Sample saved.
   • Red: ❌ Connection error (check EdukaAI is running)
   • Yellow: ⚠️ Duplicate skipped

Step 3: View in EdukaAI

1. Open EdukaAI at http://localhost:3030
2. Go to your dataset (or "Default Dataset")
3. You'll see your exported conversation!
4. Review, edit, or export it to training formats (Alpaca, ShareGPT, etc.)

💡 Tip: The export uses your default category and quality rating from the plugin settings. You can edit these in EdukaAI after export if needed!

---

🔧 Troubleshooting

"Cannot connect to EdukaAI" Error

Problem: Plugin can't reach EdukaAI server
Solution:

1. Check EdukaAI is running:

   curl http://localhost:3030/api/health
   # or start it:
   npx @elgap/edukaai

2. For Docker Users - Check your endpoint URL:

   macOS/Windows: Should use http://host.docker.internal:3030 (default)

   # Test from inside container
   docker exec open-webui curl http://host.docker.internal:3030/api/health

   Linux: Must use host IP, not host.docker.internal

   # Find your host IP
   ip addr show docker0 | grep inet
   # Usually: 172.17.0.1
   
   # Update plugin setting: http://172.17.0.1:3030

3. Test the connection manually:

   # From inside OpenWebUI container
   docker exec -it open-webui /bin/sh
   curl http://host.docker.internal:3030/api/capture -X POST \
     -H "Content-Type: application/json" \
     -d '{"source":"test","records":[]}'
   exit

"No conversation to export" Error

Problem: Clicked export without having a back-and-forth conversation
Solution: Make sure you have at least one user message AND one assistant response

Export Button Not Visible

Problem: Can't see the export button under messages
Solutions:

1. Check plugin is enabled (toggle is ON)
2. Refresh the page (F5)
3. Try a different browser
4. Check browser console for JavaScript errors

"422 Unprocessable Entity" Error

Problem: Function import failed
Solutions:

1. Try the raw GitHub URL instead of the repo URL
2. Check your OpenWebUI version is 0.3.0 or higher
3. Use Method 3 (Manual Copy) as fallback

Plugin Installed But Not Working

Problem: Plugin shows as enabled but nothing happens when clicking export
Solutions:

1. Check EdukaAI is running and accessible
2. Verify settings in the gear icon (especially EDUKAAI_ENDPOINT)
3. Check browser's Network tab for API errors
4. Try restarting OpenWebUI

---

🎓 Pro Tips

Building a Quality Dataset

1. Export selectively: Only save the best conversations
2. Configure defaults wisely: Set DEFAULT_CATEGORY and DEFAULT_QUALITY in the plugin settings to match your most common use case
3. Curate in EdukaAI: The export uses default settings, but you can edit category, quality, and add tags in EdukaAI after export
4. Rate honestly: Set default quality to 4 or 5 in plugin settings, then adjust individual samples in EdukaAI if needed
5. Export in batches: Don't export everything at once - curate as you go

Keyboard Shortcuts

Currently, the plugin works via mouse click. Future versions may add keyboard shortcuts.

Exporting Older Conversations

The plugin captures the last message pair. To export older exchanges:

1. Click the regenerate button on that specific response
2. Then click export

Working with File Attachments

If you share files in the conversation:

• The plugin automatically captures file names and content
• In EdukaAI, you'll see the files in the context.files field
• Great for code review datasets!

Setting Up Multiple Categories

If you work with different types of conversations:

• You can install the plugin multiple times with different default categories
• Or export everything with one default category and organize in EdukaAI later

---

📚 Next Steps

Now that you have the plugin working:

1. Explore EdukaAI: Learn how to organize, filter, and export your dataset
2. Set Quality Standards: Decide what makes a 5-star training example for your use case
3. Build Your Dataset: Export 50-100 high-quality examples
4. Fine-Tune: Use EdukaAI's export features to create training data for your LLM

---

🤝 Getting Help

Stuck? Here are your options:

1. Check this guide again - Most issues are covered in Troubleshooting
2. OpenWebUI Discord - https://discord.gg/5rJgQTnV4s
3. EdukaAI Issues - https://github.com/ElGap/edukaai/issues
4. This Plugin's Issues - https://github.com/ElGap/edukaai-openwebui/issues

---

🎉 You Did It!

You now have a seamless workflow:

• Chat in OpenWebUI 💬
• Export great conversations with one click 📤
• Build a curated dataset in EdukaAI 📊
• Train better AI models! 🤖

Happy training data collection! 🚀

---

Last updated: 2026-03-19
Plugin version: 0.1.0-beta.0