Initial Commit

docs/setup/searxng.md

@@ -0,0 +1,45 @@
+# SearXNG — needed by `web_search` and `find_datasheet`
+
+**Nothing to set up.** SearXNG is a container in this project's own `docker-compose.yml`
+and starts with the rest of the stack. This page is for when it is not returning results.
+
+## What it is
+
+A metasearch front end. It queries several engines and merges the results; owuitools never
+talks to a search engine directly. It has no API key and no account.
+
+It lives **inside the guarded network namespace**, sharing it with the tool server, so it
+is not reachable from your LAN or from the internet, and it can only reach the outside
+world through squid. That is deliberate: it takes a query string from a language model, and
+anything that takes model-controlled input belongs behind the same filter the rest of the
+suite is behind.
+
+## Its configuration
+
+`configs/services/searxng.settings.yml`. The parts worth knowing about:
+
+- **`server.secret_key`** — generate your own with `openssl rand -hex 32`. It signs
+  SearXNG's own session data. The shipped file has a placeholder.
+- **`server.limiter: false`** — its bot-detection is off, because the only client is the
+  tool server on a private network, and the limiter rejects programmatic queries.
+- **The engine list.** Which engines are on is a *measurement*, not a preference: some
+  block datacentre IPs, some rate-limit hard, some serve CAPTCHAs. The comments in the file
+  say what was observed and when. **Those observations were made from one egress IP and may
+  not hold for yours** — if results are thin, this list is the first thing to change.
+
+After editing it: `docker compose restart searxng`.
+
+## Checking it
+
+```sh
+./tests/try-tool.sh web_search '{"query": "systemd socket activation"}' | head -20
+```
+
+## If it returns nothing
+
+1. `docker compose logs searxng --tail 50` — engine failures are logged individually, so
+   you can see which ones are refusing.
+2. Check squid is up: SearXNG's only route out is `owuitools-egress`.
+3. Try a different engine set. An engine that blocks your IP fails silently from the
+   model's point of view: the search simply comes back empty, which reads as "nothing was
+   written about this" rather than "the search was refused".