Merge pull request #1287 from AnishSarkar22/fix/docker-host-gateway

feat: add internal backend URL configuration, internal host gateway & Ollama docs

docker/.env.example

@@ -71,6 +71,7 @@ EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
 # BACKEND_URL=https://api.yourdomain.com
 # NEXT_PUBLIC_FASTAPI_BACKEND_URL=https://api.yourdomain.com
 # NEXT_PUBLIC_ZERO_CACHE_URL=https://zero.yourdomain.com
+# FASTAPI_BACKEND_INTERNAL_URL=http://backend:8000
 
 # ------------------------------------------------------------------------------
 # Zero-cache (real-time sync)

docker/docker-compose.dev.yml

@@ -77,6 +77,8 @@ services:
       - shared_temp:/shared_tmp
     env_file:
       - ../surfsense_backend/.env
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       - DATABASE_URL=${DATABASE_URL:-postgresql+asyncpg://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}}
       - CELERY_BROKER_URL=${REDIS_URL:-redis://redis:6379/0}
@@ -118,6 +120,8 @@ services:
       - shared_temp:/shared_tmp
     env_file:
       - ../surfsense_backend/.env
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       - DATABASE_URL=${DATABASE_URL:-postgresql+asyncpg://${DB_USER:-postgres}:${DB_PASSWORD:-postgres}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}}
       - CELERY_BROKER_URL=${REDIS_URL:-redis://redis:6379/0}

docker/docker-compose.yml

@@ -60,6 +60,8 @@ services:
       - shared_temp:/shared_tmp
     env_file:
       - .env
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://${DB_USER:-surfsense}:${DB_PASSWORD:-surfsense}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}}
       CELERY_BROKER_URL: ${REDIS_URL:-redis://redis:6379/0}
@@ -100,6 +102,8 @@ services:
       - shared_temp:/shared_tmp
     env_file:
       - .env
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
     environment:
       DATABASE_URL: ${DATABASE_URL:-postgresql+asyncpg://${DB_USER:-surfsense}:${DB_PASSWORD:-surfsense}@${DB_HOST:-db}:${DB_PORT:-5432}/${DB_NAME:-surfsense}}
       CELERY_BROKER_URL: ${REDIS_URL:-redis://redis:6379/0}
@@ -198,6 +202,7 @@ services:
       NEXT_PUBLIC_FASTAPI_BACKEND_AUTH_TYPE: ${AUTH_TYPE:-LOCAL}
       NEXT_PUBLIC_ETL_SERVICE: ${ETL_SERVICE:-DOCLING}
       NEXT_PUBLIC_DEPLOYMENT_MODE: ${DEPLOYMENT_MODE:-self-hosted}
+      FASTAPI_BACKEND_INTERNAL_URL: ${FASTAPI_BACKEND_INTERNAL_URL:-http://backend:8000}
     labels:
       - "com.centurylinklabs.watchtower.enable=true"
     depends_on:

surfsense_web/app/api/zero/query/route.ts

@@ -5,7 +5,10 @@ import type { Context } from "@/types/zero";
 import { queries } from "@/zero/queries";
 import { schema } from "@/zero/schema";
 
-const backendURL = process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL || "http://localhost:8000";
+const backendURL =
+	process.env.FASTAPI_BACKEND_INTERNAL_URL ||
+	process.env.NEXT_PUBLIC_FASTAPI_BACKEND_URL ||
+	"http://localhost:8000";
 
 async function authenticateRequest(
 	request: Request

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
 }

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)