# SearXNG 
Web Search Setup Guide for Open WebUI

## What This Does
This guide will add internet search capabilities to your Open WebUI installation. Your AI will be able to search the web in real-time to answer questions about current events, news, and information beyond its training data.

---

## Prerequisites
- Docker and Docker Compose installed
- Open WebUI already running
- Terminal/command line access
- Basic familiarity with terminal commands

---

## Installation Steps

### Step 1: Create Setup Directory
Open your terminal and run:

```bash
mkdir searxng-setup
cd searxng-setup
```

### Step 2: Create Docker Compose File
Create a new file called `docker-compose.yml`:

```bash
nano docker-compose.yml
```

Paste the following configuration:

```yaml
services:
  searxng:
    container_name: searxng
    image: searxng/searxng:latest
    ports:
      - "8080:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_HOSTNAME=localhost:8080/
    restart: unless-stopped
    logging:
      driver: "json-file"
      options:
        max-size: "1m"
        max-file: "1"
```

Save the file:
- Press `Ctrl + X`
- Press `Y` to confirm
- Press `Enter` to save

### Step 3: Generate Initial Configuration
Start the container briefly to create the configuration files:

```bash
docker compose up -d
sleep 10
docker compose down
```

### Step 4: Enable JSON Format Support
Open WebUI needs JSON format support to communicate with SearXNG. Edit the settings file:

```bash
sudo nano searxng/settings.yml
```

Find this section (around line 64):
```yaml
search:
  # formats: [html, csv, json, rss]
  formats:
    - html
```

Change it to:
```yaml
search:
  # formats: [html, csv, json, rss]
  formats:
    - html
    - json
```

**Important:** Make sure `- json` is indented with exactly 4 spaces (same as `- html`).

Save the file:
- Press `Ctrl + X`
- Press `Y`
- Press `Enter`

### Step 5: Start SearXNG
Start the SearXNG container:

```bash
docker compose up -d
```

### Step 6: Verify SearXNG is Working
Wait a few seconds, then test:

```bash
sleep 5
curl "http://localhost:8080/search?q=test&format=json"

curl "http://100.87.1.24:8888/search?q=test&format=json"
```

You should see JSON output with search results. If you see HTML or an error, go back to Step 4 and verify the JSON format was added correctly.

---

## Configure Open WebUI

### Step 1: Access Admin Settings
1. Open your Open WebUI in a web browser (usually `http://localhost:3000`)
2. Click your **profile icon** in the top right corner
3. Select **Admin Panel**
4. Navigate to **Settings** → **Web Search**

### Step 2: Configure Web Search Settings
Set the following options:

- **Enable Web Search**: Toggle **ON** (switch should be blue/highlighted)
- **Web Search Engine**: Select **"searxng"** from the dropdown menu
- **Searxng Query URL**: Enter one of the following:
  ```
  http://searxng:8080/search?q=<query>
  ```
  *(If this doesn't work, try: `http://host.docker.internal:8080/search?q=<query>`)*

- **Search Result Count**: Set to `3` (or your preference)
- **Concurrent Requests**: Set to `10` (or your preference)

### Step 3: Save Configuration
Scroll to the bottom and click **Save**.

---

## Using Web Search

### How to Enable Web Search in a Chat

1. **Open any chat** in Open WebUI
2. **Look for the `+` button** next to the message input field at the bottom
3. **Click the `+` button** to reveal additional options
4. **Toggle "Web Search" to ON** (it should turn blue/highlighted)
5. **Type your question** and send

### Important Notes

⚠️ **Web Search must be enabled manually for each chat session**
- The toggle automatically turns OFF when you:
  - Reload the page
  - Switch to a different chat
  - Start a new conversation
- You must turn it ON every time you want the AI to search the web

### Example Questions to Test

Once Web Search is enabled, try asking:
- "What's the weather forecast for tomorrow?"
- "What happened in the news today?"
- "What are the current trending topics?"
- "Find recent information about [specific topic]"

---

## Troubleshooting

### SearXNG Container Won't Start

**Check logs:**
```bash
docker logs searxng
```

**Common issue:** YAML syntax error in settings.yml
- Make sure the `- json` line is indented exactly like `- html` (4 spaces)
- No tabs, only spaces

### Web Search Not Working in Open WebUI

**Checklist:**
1. ✅ Is SearXNG container running? Check with: `docker ps`
2. ✅ Did you enable Web Search in Admin Panel settings?
3. ✅ Did you select "searxng" as the search engine?
4. ✅ Did you enter the Searxng Query URL correctly?
5. ✅ Did you toggle Web Search ON in the chat (click the `+` button)?

### Testing Connectivity

From Open WebUI container:
```bash
docker exec -it open-webui curl "http://searxng:8080/search?q=test&format=json"
```

If this fails, try changing the URL in Open WebUI settings to:
```
http://host.docker.internal:8080/search?q=<query>
```

### 403 Forbidden Error

This means JSON format is not enabled. Go back to Step 4 and verify:
- The `- json` line exists under `formats:`
- It's indented correctly (4 spaces, same as `- html`)
- You restarted the container after making changes

---

## Maintenance

### Viewing Logs
```bash
docker logs searxng
```

### Restarting SearXNG
```bash
cd searxng-setup
docker compose restart
```

### Stopping SearXNG
```bash
cd searxng-setup
docker compose down
```

### Updating SearXNG
```bash
cd searxng-setup
docker compose pull
docker compose up -d
```

---

## Understanding the Setup

### What is SearXNG?
SearXNG is a privacy-respecting metasearch engine that queries multiple search engines (Google, Bing, DuckDuckGo, etc.) and aggregates the results. It doesn't track users or store search history.

### How Does This Work?
1. You enable Web Search in Open WebUI
2. You ask the AI a question
3. Open WebUI sends a search query to SearXNG
4. SearXNG searches multiple engines and returns results
5. The AI uses those results to answer your question

### Port Information
- **Port 8080**: SearXNG web interface and API
- Your Open WebUI container communicates with SearXNG over this port

---

## Quick Reference Card

### Starting Fresh
```bash
cd searxng-setup
docker compose down
sudo rm -rf searxng/
docker compose up -d
sleep 10
docker compose down
# Edit searxng/settings.yml to add JSON support
docker compose up -d
```

### Daily Use Checklist
1. ✅ Open WebUI chat
2. ✅ Click `+` button
3. ✅ Toggle "Web Search" ON
4. ✅ Ask your question

### URLs to Remember
- **Container name URL**: `http://searxng:8080/search?q=<query>`
- **Alternative URL**: `http://host.docker.internal:8080/search?q=<query>`
- **Bridge IP URL**: `http://172.17.0.1:8080/search?q=<query>`

---

## Support

If you continue to experience issues:
1. Check Docker logs: `docker logs searxng`
2. Verify container is running: `docker ps | grep searxng`
3. Test connectivity: `curl "http://localhost:8080/search?q=test&format=json"`
4. Review Open WebUI logs for error messages

---

**Setup Complete!** 🎉

You now have web search capabilities in your Open WebUI installation. Remember to toggle Web Search ON in each chat session when you need it.


