From fbb79362343023de48cd595aea3ef2794bb3be10 Mon Sep 17 00:00:00 2001
From: jaberjaber23 <jaberib647@gmail.com>
Date: Tue, 12 May 2026 15:30:40 +0300
Subject: [PATCH] docker docs

---
 docker-compose.yml      |  5 +++
 docs/getting-started.md | 17 +++++++++
 docs/troubleshooting.md | 76 +++++++++++++++++++++++++++++++++++++++++
 3 files changed, 98 insertions(+)

diff --git a/docker-compose.yml b/docker-compose.yml
index b09f85f0..f5717fa2 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -11,6 +11,11 @@ services:
       - "4200:4200"
     volumes:
       - openfang-data:/data
+    # Uncomment to reach host services (Ollama, whisper.cpp, local Postgres)
+    # from inside the container. Required on Linux and colima. See
+    # docs/troubleshooting.md#connecting-to-host-services-from-docker.
+    # extra_hosts:
+    #   - "host.docker.internal:host-gateway"
     environment:
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
       - OPENAI_API_KEY=${OPENAI_API_KEY:-}
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 0a2d1a23..80a59471 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -82,6 +82,23 @@ cd openfang
 docker compose up -d
 ```
 
+**Reaching host services from the container.** If you run a local LLM
+(Ollama, whisper.cpp, vLLM) on the host and want the agent to call it, add
+the host-gateway bridge. Required on Linux and colima:
+
+```bash
+docker run -d \
+  --add-host=host.docker.internal:host-gateway \
+  -e OLLAMA_HOST=http://host.docker.internal:11434 \
+  -p 4200:4200 \
+  ghcr.io/rightnow-ai/openfang:latest
+```
+
+For Compose, add `extra_hosts: ["host.docker.internal:host-gateway"]` to the
+service. See [Troubleshooting → Connecting to host services from Docker](troubleshooting.md#connecting-to-host-services-from-docker)
+and the [curl-equipped overlay image](troubleshooting.md#curl-equipped-reference-image)
+if you need in-container `curl` for healthchecks.
+
 ### Verify Installation
 
 ```bash
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index c5ee68fe..d3f2b34e 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -110,6 +110,75 @@ rm ~/.config/fish/conf.d/openfang.fish
 - Port already in use: change the port mapping `-p 3001:4200`
 - Permission denied on volume mount: check directory permissions
 
+### Connecting to host services from Docker
+
+If you run OpenFang inside Docker and need to reach a service running on the
+host (Ollama on `127.0.0.1:11434`, whisper.cpp on `127.0.0.1:8090`, a local
+Postgres, etc.), `localhost` inside the container points at the container
+itself, not the host. You must opt in to the host bridge.
+
+On Docker Desktop (macOS/Windows) `host.docker.internal` resolves
+automatically. On Linux and on colima (macOS) it does not, and you must add
+the flag explicitly:
+
+```bash
+docker run --rm \
+  --add-host=host.docker.internal:host-gateway \
+  -e OLLAMA_HOST=http://host.docker.internal:11434 \
+  -p 4200:4200 \
+  ghcr.io/rightnow-ai/openfang:latest
+```
+
+Verify the bridge works:
+
+```bash
+docker exec <container> getent hosts host.docker.internal
+# 192.168.x.x  host.docker.internal
+```
+
+For Docker Compose use `extra_hosts:`:
+
+```yaml
+services:
+  openfang:
+    image: ghcr.io/rightnow-ai/openfang:latest
+    ports:
+      - "4200:4200"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      - OLLAMA_HOST=http://host.docker.internal:11434
+```
+
+Without this flag on Linux/colima, calls to host services fail silently with
+connection refused or DNS lookup errors.
+
+### Curl-equipped reference image
+
+The default `ghcr.io/rightnow-ai/openfang` image does not ship `curl`, so
+`docker exec openfang curl ...` returns `exec: curl: not found`. If you need
+in-container probes for healthchecks or egress verification, build a thin
+overlay image:
+
+```dockerfile
+# Dockerfile.curl
+FROM ghcr.io/rightnow-ai/openfang:latest
+USER root
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+Build and run:
+
+```bash
+docker build -f Dockerfile.curl -t openfang-curl:latest .
+docker run --rm openfang-curl:latest curl -s https://example.com
+```
+
+Use this variant when you need `HEALTHCHECK` directives or in-container
+diagnostics. The base image stays slim by default.
+
 ---
 
 ## Configuration Issues
@@ -596,6 +665,13 @@ docker run -d --name openfang \
   ghcr.io/rightnow-ai/openfang:latest
 ```
 
+To reach a host LLM (Ollama, vLLM, whisper.cpp) from inside the container,
+add `--add-host=host.docker.internal:host-gateway`. See
+[Connecting to host services from Docker](#connecting-to-host-services-from-docker).
+The default image does not ship `curl`; build the
+[curl-equipped overlay](#curl-equipped-reference-image) if you need
+in-container healthchecks.
+
 ### How do I protect the dashboard with a password?
 
 OpenFang has built-in dashboard authentication. Enable it in `~/.openfang/config.toml`: