diff --git a/surfsense_backend/app/services/provider_registry.py b/surfsense_backend/app/services/provider_registry.py index 8d3c03dce..d2b72cb63 100644 --- a/surfsense_backend/app/services/provider_registry.py +++ b/surfsense_backend/app/services/provider_registry.py @@ -88,7 +88,7 @@ REGISTRY: dict[str, ProviderSpec] = { Transport.OLLAMA, "ollama_chat", "ollama", - "http://ollama:11434", + "http://host.docker.internal:11434", True, "none", "Ollama", diff --git a/surfsense_web/content/docs/how-to/meta.json b/surfsense_web/content/docs/how-to/meta.json index 329b7172e..477fcafc4 100644 --- a/surfsense_web/content/docs/how-to/meta.json +++ b/surfsense_web/content/docs/how-to/meta.json @@ -1,6 +1,6 @@ { "title": "How to", - "pages": ["zero-sync", "realtime-collaboration", "web-search", "ollama"], + "pages": ["zero-sync", "realtime-collaboration", "web-search"], "icon": "Compass", "defaultOpen": false } diff --git a/surfsense_web/content/docs/how-to/ollama.mdx b/surfsense_web/content/docs/how-to/ollama.mdx deleted file mode 100644 index f5ec09e1b..000000000 --- a/surfsense_web/content/docs/how-to/ollama.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: Connect Ollama -description: Simple setup guide for using Ollama with SurfSense across local, Docker, remote, and cloud setups ---- - -# Connect Ollama - -Use this page to choose the correct **API Base URL** when adding an Ollama provider in SurfSense. - -## 1) Pick your API Base URL - -| Ollama location | SurfSense location | API Base URL | -|---|---|---| -| Same machine | No Docker | `http://localhost:11434` | -| Host machine (macOS/Windows) | Docker Desktop | `http://host.docker.internal:11434` | -| Host machine (Linux) | Docker Compose | `http://host.docker.internal:11434` | -| Same Docker Compose stack | Docker Compose | `http://ollama:11434` | -| Another machine in your network | Any | `http://:11434` | -| Public Ollama endpoint / proxy / cloud | Any | `http(s)://` | - -If SurfSense runs in Docker, do not use `localhost` unless Ollama is in the same container. - -## 2) Add Ollama in SurfSense - -Go to **Search Space Settings -> Models -> Add Model** and set: - -- Provider: `OLLAMA` -- Model name: your model tag, for example `llama3.2` or `qwen3:8b` -- API Base URL: from the table above -- API key: - - local/self-hosted Ollama: any non-empty value - - Ollama cloud/proxied auth: real key or token required by that endpoint - -Save. SurfSense validates the connection immediately. - -## 3) Common setups - -### A) SurfSense in Docker Desktop, Ollama on your host - -Use: - -```text -http://host.docker.internal:11434 -``` - -### B) Ollama as a service in the same Compose - -Use API Base URL: - -```text -http://ollama:11434 -``` - -Minimal service example: - -```yaml -ollama: - image: ollama/ollama:latest - volumes: - - ollama_data:/root/.ollama - ports: - - "11434:11434" -``` - -### C) Ollama on another machine - -Ollama binds to `127.0.0.1` by default. Make it reachable on the network: - -- Set `OLLAMA_HOST=0.0.0.0:11434` on the machine/service running Ollama -- Open firewall port `11434` -- Use `http://:11434` in SurfSense's API Base URL - -## 4) Quick troubleshooting - -| Error | Cause | Fix | -|---|---|---| -| `Cannot connect to host localhost:11434` | Wrong URL from Dockerized backend | Use `host.docker.internal` or `ollama` | -| `Cannot connect to host :11434` | Ollama not exposed on network or firewall blocked | Set `OLLAMA_HOST=0.0.0.0:11434`, allow port 11434 | -| URL starts with `/%20http://...` | Leading space in URL | Re-enter API Base URL without spaces | -| `model not found` | Model not pulled on Ollama | Run `ollama pull ` | - -If needed, test from the backend container using the same host you put in **API Base URL**: - -```bash -docker compose exec backend curl -v /api/tags -``` - -## See also - -- [Docker Installation](/docs/docker-installation/docker-compose) \ No newline at end of file diff --git a/surfsense_web/content/docs/index.mdx b/surfsense_web/content/docs/index.mdx index 4a321b376..c8540fed0 100644 --- a/surfsense_web/content/docs/index.mdx +++ b/surfsense_web/content/docs/index.mdx @@ -5,7 +5,7 @@ icon: BookOpen --- import { Card, Cards } from 'fumadocs-ui/components/card'; -import { ClipboardCheck, Download, Container, Wrench, Cable, BookOpen, FlaskConical, Heart, MessageCircle } from 'lucide-react'; +import { ClipboardCheck, Download, Container, Wrench, Cable, BookOpen, FlaskConical, Heart, MessageCircle, Cpu } from 'lucide-react'; Welcome to **SurfSense's Documentation!** Here, you'll find everything you need to get the most out of SurfSense. Dive in to explore how SurfSense can be your AI-powered research companion. @@ -34,6 +34,12 @@ Welcome to **SurfSense's Documentation!** Here, you'll find everything you need description="Set up SurfSense manually from source" href="/docs/manual-installation" /> + } + title="Local Models" + description="Connect local model servers" + href="/docs/local-models" + /> } title="Connectors" diff --git a/surfsense_web/content/docs/local-models/index.mdx b/surfsense_web/content/docs/local-models/index.mdx new file mode 100644 index 000000000..e1839a4f0 --- /dev/null +++ b/surfsense_web/content/docs/local-models/index.mdx @@ -0,0 +1,30 @@ +--- +title: Local Models +description: Connect local model servers to SurfSense +--- + +import { Card, Cards } from 'fumadocs-ui/components/card'; + +# Local Models + +SurfSense can use local model servers such as Ollama and LM Studio. + +The API Base URL is read by the SurfSense backend. If SurfSense runs in Docker, use an address the backend container can reach. + + + + + + diff --git a/surfsense_web/content/docs/local-models/lm-studio.mdx b/surfsense_web/content/docs/local-models/lm-studio.mdx new file mode 100644 index 000000000..6877786e5 --- /dev/null +++ b/surfsense_web/content/docs/local-models/lm-studio.mdx @@ -0,0 +1,92 @@ +--- +title: LM Studio +description: Connect LM Studio to SurfSense +--- + +# Connect LM Studio + +Connect to your LM Studio local server. Add it from +**Search Space Settings > Models**. + +## Base URL + +LM Studio uses an OpenAI compatible server. + +### SurfSense Runs in Docker + +Use this when SurfSense is running from Docker and LM Studio is running on your computer. + +```text +http://host.docker.internal:1234/v1 +``` + + +This is the default in SurfSense. + + +### SurfSense Runs Without Docker + +Use this when SurfSense and LM Studio both run directly on the same computer. + +```text +http://localhost:1234/v1 +``` + +### LM Studio Runs on Another Computer + +Use this when LM Studio is running on another machine in your network. + +```text +http://:1234/v1 +``` + +Replace `` with the LAN IP or domain for that machine. + +## LM Studio Setup + +1. Open LM Studio. +2. Load a model. +3. Start the local server. +4. Confirm the server listens on port `1234`. + +## Add the Connection + +1. Open Search Space Settings. +2. Go to Models. +3. Select LM Studio. +4. Set API Base URL. +5. Leave API Key empty unless your server requires one. +6. Select the models you want to enable. +7. Save the connection. + +SurfSense discovers models from `/v1/models`. If you enter the URL without `/v1`, SurfSense adds it for requests. + +## Verify + +From the host: + +```bash +curl http://localhost:1234/v1/models +``` + +From the SurfSense backend container: + +```bash +docker compose exec backend curl http://host.docker.internal:1234/v1/models +``` + +## Troubleshooting + +### Connection refused + +LM Studio is not reachable from the backend. + +Start the LM Studio server and confirm that port `1234` is open. + +### No models found + +Load a model in LM Studio, then refresh model discovery in SurfSense. + +### Endpoint returned 404 + +Use an OpenAI compatible server URL. The models endpoint must be available at `/v1/models`. diff --git a/surfsense_web/content/docs/local-models/meta.json b/surfsense_web/content/docs/local-models/meta.json new file mode 100644 index 000000000..d904a8d5c --- /dev/null +++ b/surfsense_web/content/docs/local-models/meta.json @@ -0,0 +1,6 @@ +{ + "title": "Local Models", + "pages": ["ollama", "lm-studio", "other-local-servers"], + "icon": "Cpu", + "defaultOpen": false +} diff --git a/surfsense_web/content/docs/local-models/ollama.mdx b/surfsense_web/content/docs/local-models/ollama.mdx new file mode 100644 index 000000000..b062d98b0 --- /dev/null +++ b/surfsense_web/content/docs/local-models/ollama.mdx @@ -0,0 +1,102 @@ +--- +title: Ollama +description: Connect Ollama to SurfSense +--- + +# Connect Ollama + +Connect to your Ollama local server. Add it from +**Search Space Settings > Models**. + +## Base URL + +Choose the URL from where the SurfSense backend runs. + +### SurfSense Runs in Docker + +Use this when SurfSense is running from Docker and Ollama is running on your computer. + +```text +http://host.docker.internal:11434 +``` + + +This is the default in SurfSense. + + +### Ollama Runs in Docker + +Use this only when Ollama is a service in the same Compose stack as SurfSense. + +```text +http://ollama:11434 +``` + +### SurfSense Runs Without Docker + +Use this when SurfSense and Ollama both run directly on the same computer. + +```text +http://localhost:11434 +``` + +### Ollama Runs on Another Computer + +Use this when Ollama is running on another machine in your network. + +```text +http://:11434 +``` + +Replace `` with the LAN IP or domain for that machine. + +## Add the Connection + +1. Open Search Space Settings. +2. Go to Models. +3. Select Ollama. +4. Set API Base URL. +5. Leave API Key empty unless your endpoint needs one. +6. Select the models you want to enable. +7. Save the connection. + +Do not add `/v1` to the URL. SurfSense uses Ollama native routes such as `/api/version` and `/api/tags`. + +## Verify + +From the host: + +```bash +curl http://localhost:11434/api/version +``` + +From the SurfSense backend container: + +```bash +docker compose exec backend curl http://host.docker.internal:11434/api/version +docker compose exec backend curl http://host.docker.internal:11434/api/tags +``` + +## Troubleshooting + +### Name or service not known + +The backend cannot resolve the host name. + +Use `http://host.docker.internal:11434` unless you run Ollama as a Compose service named `ollama`. + +### Connection refused + +Ollama is not reachable from the backend. + +Start Ollama and confirm that port `11434` is open. + +### No models found + +Pull at least one model: + +```bash +ollama pull llama3.2 +``` + +Then refresh model discovery in SurfSense. diff --git a/surfsense_web/content/docs/local-models/other-local-servers.mdx b/surfsense_web/content/docs/local-models/other-local-servers.mdx new file mode 100644 index 000000000..669684929 --- /dev/null +++ b/surfsense_web/content/docs/local-models/other-local-servers.mdx @@ -0,0 +1,109 @@ +--- +title: Other Local Servers +description: Connect local OpenAI compatible model servers +--- + +# Connect Other Local Servers + +Connect to llama.cpp, vLLM, LocalAI, LiteLLM Proxy, and other servers +that expose OpenAI compatible routes. + +SurfSense discovers models from: + +```text +/v1/models +``` + +Chat requests use the same `/v1` base URL. + +## Pick Your Setup + +Use one of these URL patterns. + +### SurfSense Runs in Docker + +Use this when SurfSense is running from Docker and the model server is running on your computer. + +```text +http://host.docker.internal:/v1 +``` + +Common ports: + +| Server | Port | +|---|---| +| llama.cpp | `10000` | +| vLLM | `8000` | +| LocalAI | `8080` | +| LiteLLM Proxy | `4000` | +| text-generation-webui | `5000` | + +### SurfSense Runs Without Docker + +Use this when SurfSense and the model server both run directly on the same computer. + +```text +http://localhost:/v1 +``` + +### Model Server Runs on Another Computer + +Use this when the model server is running on another machine in your network. + +```text +http://:/v1 +``` + +## Add the Connection + +1. Open Search Space Settings. +2. Go to Models. +3. Select OpenAI Compatible. +4. Set API Base URL. +5. Add an API Key only if your server requires one. +6. Select the models you want to enable. +7. Save the connection. + +If you enter the URL without `/v1`, SurfSense adds `/v1` for requests. + +## Verify + +From the host: + +```bash +curl http://localhost:/v1/models +``` + +From the SurfSense backend container: + +```bash +docker compose exec backend curl http://host.docker.internal:/v1/models +``` + +A working server returns JSON with a `data` array. + +## When Not to Use This + +Use the Ollama provider for Ollama. It uses native routes such as `/api/tags`. + +Use the LM Studio provider for LM Studio. Its default URL is already set. + +## Troubleshooting + +### Endpoint returned 404 + +The server does not expose `/v1/models`. + +Enable the server's OpenAI compatible mode. + +### Connection refused + +The backend cannot reach the server. + +Check that the server is running and that the port is open. + +### No models found + +The server returned an empty model list. + +Load or serve a model, then refresh model discovery in SurfSense. diff --git a/surfsense_web/content/docs/meta.json b/surfsense_web/content/docs/meta.json index 74be10600..435e49f9f 100644 --- a/surfsense_web/content/docs/meta.json +++ b/surfsense_web/content/docs/meta.json @@ -9,6 +9,7 @@ "installation", "manual-installation", "docker-installation", + "local-models", "messaging-channels", "connectors", "how-to", diff --git a/surfsense_web/lib/source.ts b/surfsense_web/lib/source.ts index f71e8b688..13fb58f22 100644 --- a/surfsense_web/lib/source.ts +++ b/surfsense_web/lib/source.ts @@ -4,6 +4,7 @@ import { ClipboardCheck, Compass, Container, + Cpu, Download, FlaskConical, Heart, @@ -25,6 +26,7 @@ const DOCS_ICONS: Record = { ClipboardCheck, Compass, Container, + Cpu, Download, FlaskConical, Heart,