From 7c23f31dc001f2272e4b82f9350705ac57f48a58 Mon Sep 17 00:00:00 2001
From: Anish Sarkar <104695310+AnishSarkar22@users.noreply.github.com>
Date: Tue, 21 Apr 2026 23:25:43 +0530
Subject: [PATCH] feat: add Ollama setup guide to documentation

---
 surfsense_web/content/docs/how-to/meta.json  |  2 +-
 surfsense_web/content/docs/how-to/ollama.mdx | 90 ++++++++++++++++++++
 2 files changed, 91 insertions(+), 1 deletion(-)
 create mode 100644 surfsense_web/content/docs/how-to/ollama.mdx

diff --git a/surfsense_web/content/docs/how-to/meta.json b/surfsense_web/content/docs/how-to/meta.json
index 477fcafc4..329b7172e 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"],
+	"pages": ["zero-sync", "realtime-collaboration", "web-search", "ollama"],
 	"icon": "Compass",
 	"defaultOpen": false
 }
diff --git a/surfsense_web/content/docs/how-to/ollama.mdx b/surfsense_web/content/docs/how-to/ollama.mdx
new file mode 100644
index 000000000..48b231705
--- /dev/null
+++ b/surfsense_web/content/docs/how-to/ollama.mdx
@@ -0,0 +1,90 @@
+---
+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://<lan-ip>:11434` |
+| Public Ollama endpoint / proxy / cloud | Any | `http(s)://<your-domain-or-endpoint>` |
+
+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 -> Agent 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://<lan-ip>: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 <lan-ip>: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 <model>` |
+
+If needed, test from the backend container using the same host you put in **API Base URL**:
+
+```bash
+docker compose exec backend curl -v <YOUR_API_BASE_URL>/api/tags
+```
+
+## See also
+
+- [Docker Installation](/docs/docker-installation/docker-compose)
\ No newline at end of file