fix: Docker networking and permissions documentation (#500)

* chore: force env file on api

* fix: Docker networking and permissions documentation

- Add HOSTNAME=0.0.0.0 as default in Dockerfiles for reverse proxy compatibility
- Document Linux extra_hosts requirement for host.docker.internal
- Add user: root to SurrealDB examples for bind mount permissions on Linux
- Update environment reference and reverse proxy docs

Fixes #483, fixes #485, fixes #409

Dockerfile

@@ -76,6 +76,9 @@ COPY . /app
 ENV UV_NO_SYNC=1
 ENV VIRTUAL_ENV=/app/.venv
 
+# Bind Next.js to all interfaces (required for Docker networking and reverse proxies)
+ENV HOSTNAME=0.0.0.0
+
 # Copy built frontend from builder stage
 COPY --from=builder /app/frontend/.next/standalone /app/frontend/
 COPY --from=builder /app/frontend/.next/static /app/frontend/.next/static

Dockerfile.single

@@ -59,6 +59,9 @@ COPY --from=frontend-builder /app/frontend/.next/standalone /app/frontend/
 COPY --from=frontend-builder /app/frontend/.next/static /app/frontend/.next/static
 COPY --from=frontend-builder /app/frontend/public /app/frontend/public
 
+# Bind Next.js to all interfaces (required for Docker networking and reverse proxies)
+ENV HOSTNAME=0.0.0.0
+
 # Setup directories and permissions
 RUN mkdir -p /app/data /mydata
 

Makefile

@@ -134,9 +134,9 @@ full:
 
 
 api:
-	uv run run_api.py
+	uv run --env-file .env run_api.py
+
 
-# === Worker Management ===
 .PHONY: worker worker-start worker-stop worker-restart
 
 worker: worker-start

docs/1-INSTALLATION/docker-compose.md

@@ -37,6 +37,7 @@ services:
   surrealdb:
     image: surrealdb/surrealdb:v2
     command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
+    user: root  # Required for bind mounts on Linux (SurrealDB runs as non-root by default)
     ports:
       - "8000:8000"
     volumes:
@@ -287,6 +288,29 @@ docker compose down -v
 docker compose up -d
 ```
 
+### Database Permission Denied (Linux)
+
+If you see `Permission denied` or `Failed to create RocksDB directory` in SurrealDB logs:
+
+```bash
+docker compose logs surrealdb | grep -i permission
+```
+
+This happens because SurrealDB runs as a non-root user but Docker creates bind mount directories as root. Add `user: root` to the surrealdb service:
+
+```yaml
+surrealdb:
+  image: surrealdb/surrealdb:v2
+  user: root  # Fix for Linux bind mount permissions
+  # ... rest of config
+```
+
+Then restart:
+```bash
+docker compose down -v
+docker compose up -d
+```
+
 ---
 
 ## Next Steps

docs/5-CONFIGURATION/environment-reference.md

@@ -12,6 +12,7 @@ Comprehensive list of all environment variables available in Open Notebook.
 | `INTERNAL_API_URL` | No | http://localhost:5055 | Internal API URL for Next.js server-side proxying |
 | `API_CLIENT_TIMEOUT` | No | 300 | Client timeout in seconds (how long to wait for API response) |
 | `OPEN_NOTEBOOK_PASSWORD` | No | None | Password to protect Open Notebook instance |
+| `HOSTNAME` | No | `0.0.0.0` (in Docker) | Network interface for Next.js to bind to. Default `0.0.0.0` ensures accessibility from reverse proxies |
 
 ---
 

docs/5-CONFIGURATION/ollama.md

@@ -81,10 +81,30 @@ export OLLAMA_HOST=0.0.0.0:11434
 ollama serve
 ```
 
+**⚠️ LINUX USERS: Extra configuration required!**
+
+On Linux, `host.docker.internal` doesn't resolve automatically like it does on macOS/Windows. You must add `extra_hosts` to your docker-compose.yml:
+
+```yaml
+services:
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    # ... other settings ...
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      - OLLAMA_API_BASE=http://host.docker.internal:11434
+```
+
+Without this, you'll get connection errors like:
+```
+httpcore.ConnectError: [Errno -2] Name or service not known
+```
+
 **Why `host.docker.internal`?**
 - Docker containers can't reach `localhost` on the host
 - `host.docker.internal` is Docker's special hostname for the host machine
-- Available on Docker Desktop for Mac/Windows and recent Linux versions
+- Available on Docker Desktop for Mac/Windows; **requires `extra_hosts` on Linux**
 
 **Why `OLLAMA_HOST=0.0.0.0:11434`?**
 - By default, Ollama only binds to localhost and rejects external connections
@@ -317,6 +337,8 @@ docker exec -it open-notebook bash
 curl http://host.docker.internal:11434/api/tags
 ```
 
+**If this fails on Linux** with "Name or service not known", you need to add `extra_hosts` to your docker-compose.yml. See the [Docker-Specific Troubleshooting](#docker-specific-troubleshooting) section below.
+
 **3. Models not downloading**
 
 **Check disk space:**
@@ -409,14 +431,31 @@ ollama run gemma3:12b "Hello, world"
 
 ### Docker-Specific Troubleshooting
 
-**1. Host networking on Linux:**
+**1. Linux: `host.docker.internal` not resolving (Most Common)**
+
+If you see `Name or service not known` errors on Linux, add `extra_hosts` to your docker-compose.yml:
+
+```yaml
+services:
+  open_notebook:
+    image: lfnovo/open_notebook:v1-latest-single
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    environment:
+      - OLLAMA_API_BASE=http://host.docker.internal:11434
+    # ... rest of your config
+```
+
+This maps `host.docker.internal` to your host machine's IP. macOS/Windows Docker Desktop does this automatically, but Linux requires explicit configuration.
+
+**2. Host networking on Linux (alternative):**
 ```bash
 # Use host networking if host.docker.internal doesn't work
 docker run --network host lfnovo/open_notebook:v1-latest-single
 export OLLAMA_API_BASE=http://localhost:11434
 ```
 
-**2. Custom bridge network:**
+**3. Custom bridge network:**
 ```yaml
 version: '3.8'
 networks:

docs/5-CONFIGURATION/reverse-proxy.md

@@ -108,6 +108,8 @@ API_URL=https://your-domain.com
 
 **Important**: Set `API_URL` to your public URL (with https://).
 
+**Note on HOSTNAME**: The Docker images set `HOSTNAME=0.0.0.0` by default, which ensures Next.js binds to all interfaces and is accessible from reverse proxies. You typically don't need to set this manually.
+
 ---
 
 ## Understanding API_URL