From b1d4c5cd34afd58db189a72c32d392e89f3e43bb Mon Sep 17 00:00:00 2001 From: Luis Novo Date: Thu, 29 Jan 2026 23:54:17 -0300 Subject: [PATCH] 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 | 3 ++ Dockerfile.single | 3 ++ Makefile | 4 +- docs/1-INSTALLATION/docker-compose.md | 24 ++++++++++ docs/5-CONFIGURATION/environment-reference.md | 1 + docs/5-CONFIGURATION/ollama.md | 45 +++++++++++++++++-- docs/5-CONFIGURATION/reverse-proxy.md | 2 + 7 files changed, 77 insertions(+), 5 deletions(-) diff --git a/Dockerfile b/Dockerfile index 57e4ba9..9e30e09 100644 --- a/Dockerfile +++ b/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 diff --git a/Dockerfile.single b/Dockerfile.single index 901d763..822a5d6 100644 --- a/Dockerfile.single +++ b/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 diff --git a/Makefile b/Makefile index b71b4da..9ec8198 100644 --- a/Makefile +++ b/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 diff --git a/docs/1-INSTALLATION/docker-compose.md b/docs/1-INSTALLATION/docker-compose.md index feaff53..695aee2 100644 --- a/docs/1-INSTALLATION/docker-compose.md +++ b/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 diff --git a/docs/5-CONFIGURATION/environment-reference.md b/docs/5-CONFIGURATION/environment-reference.md index 76cc532..b7e8a26 100644 --- a/docs/5-CONFIGURATION/environment-reference.md +++ b/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 | --- diff --git a/docs/5-CONFIGURATION/ollama.md b/docs/5-CONFIGURATION/ollama.md index 60ca1fd..7818604 100644 --- a/docs/5-CONFIGURATION/ollama.md +++ b/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: diff --git a/docs/5-CONFIGURATION/reverse-proxy.md b/docs/5-CONFIGURATION/reverse-proxy.md index f7dd1ad..3a25a23 100644 --- a/docs/5-CONFIGURATION/reverse-proxy.md +++ b/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