From 42be5b48675577d86ecc25e7debaf79c01b73f3b Mon Sep 17 00:00:00 2001
From: Shree Bohara <shreetbohara@gmail.com>
Date: Sun, 9 Aug 2026 08:39:59 -0700
Subject: [PATCH] Correct docker/README.md: it described volumes and services
 that do not exist

Every claim below was checked against docker/docker-compose.yml and config.py.

- Ollama from inside a container: OLLAMA_BASE_URL defaults to
  http://localhost:11434, which inside the api container is the container itself,
  not the host. This became reachable only now that compose forwards the variable
  (previously the Ollama path was unusable under Docker at all), so document
  host.docker.internal plus the extra_hosts line Linux needs.
- Data Persistence was wrong in both mechanism and names. It claimed named volumes
  `api-data` and `repos-data`; neither exists anywhere in the compose file. The api
  service bind-mounts ../data:/app/data, so state lives in the working tree and
  survives `compose down`. Noted the root-owned-files consequence and the declared
  but never mounted `data:` volume.
- Services omitted redis, which the file defines and which api declares
  depends_on, so it is not optional. Flagged that it is published unauthenticated.
- `docker-compose up` -> `docker compose up`; the v1 binary is end-of-life.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 docker/README.md | 47 +++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 43 insertions(+), 4 deletions(-)

diff --git a/docker/README.md b/docker/README.md
index 97b52f7..d055326 100644
--- a/docker/README.md
+++ b/docker/README.md
@@ -15,7 +15,7 @@ OPENAI_API_KEY=sk-...
 
 2. Build and run:
 ```bash
-docker-compose up --build
+docker compose up --build
 ```
 
 3. Access:
@@ -27,9 +27,48 @@ docker-compose up --build
 
 - **api**: FastAPI backend (port 8000)
 - **web**: Next.js frontend (port 3000)
+- **redis**: cache and rate-limit backend (port 6379). `api` declares
+  `depends_on: redis`, so it is not optional under compose.
+
+Note that redis is published on 6379 with no password. That is fine on a laptop;
+do not expose it on a shared or public host.
 
 ## Data Persistence
 
-Data is stored in Docker volumes:
-- `api-data`: Database and ChromaDB
-- `repos-data`: Cloned repositories
+The `api` service **bind-mounts** the repo's `data/` directory:
+
+```
+../data  ->  /app/data
+```
+
+So the SQLite database, the ChromaDB directory and every cloned repository live in
+`data/` in your working tree, not in a Docker-managed volume, and they survive
+`docker compose down`. Two consequences worth knowing:
+
+- The container runs as root, so files it creates under `data/` are root-owned on
+  the host.
+- `docker-compose.yml` also declares a named volume `data:` that nothing mounts.
+  It has no effect; the bind mount above is what is actually used.
+
+## Using Ollama from inside Docker
+
+`OLLAMA_BASE_URL` defaults to `http://localhost:11434`, which is correct when you
+run the API directly on your machine but **wrong inside a container** — there,
+`localhost` is the container itself, not your host. If you set
+`LLM_PROVIDER=ollama` or `EMBEDDING_PROVIDER=ollama` in `docker/.env`, also set:
+
+```bash
+OLLAMA_BASE_URL=http://host.docker.internal:11434
+```
+
+On Docker Desktop (macOS/Windows) that name resolves automatically. On Linux it
+does not unless you add it to the `api` service:
+
+```yaml
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+```
+
+Also pull the model first (`ollama pull nomic-embed-text`) — a missing model now
+fails fast with a clear error rather than embedding your whole repository as zero
+vectors.