docs: stop teaching 0.0.0.0 SurrealDB port exposure in setup snippets (#1060)

* docs: stop teaching 0.0.0.0 SurrealDB port exposure in setup snippets

Bind port 8000 to 127.0.0.1 in every compose and docker run snippet
(README, quick starts, installation, configuration and development docs,
and the examples/docker-compose-*.yml files), matching the shipped
docker-compose.yml from #1025. Drop the redundant --bind 0.0.0.0:8000
from containerized surreal start commands (it is the in-container
default) and add !override to docker-compose.override.yml.example so the
opt-in re-publish actually replaces the base port binding instead of
colliding with it. Docs that discuss reaching the database from another
machine now point at the override example plus a firewall/SSH-tunnel
note.

Closes #1034

* docs: parameterize creds in manual compose example, note Compose version for !override

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.12.0] - 2026-07-12
 
+### Fixed
+- Setup snippets no longer teach publishing SurrealDB on `0.0.0.0` — the compose and `docker run` examples across the README, quick starts, installation, configuration and development docs, and the `examples/docker-compose-*.yml` files now bind port 8000 to `127.0.0.1` (matching the shipped `docker-compose.yml`), with docs pointing to `docker-compose.override.yml.example` for opt-in remote access behind a firewall or SSH tunnel; the override example itself gained the `!override` tag it needs to actually replace the base port binding instead of colliding with it (#1034)
+
 ### Added
 - Docs: cubic platform mechanics recorded as comments in `cubic.yaml` (agent limits, config precedence, memory/learning) and a "Merging PR Batches" playbook added to the maintainer guide (squash policy, CHANGELOG conflict resolution, fork rebases, competing-PR checks) (#1086)
 - New `GET /api/providers` endpoint returning provider metadata from the registry (name, display name, modalities, docs URL, whether it is configured via environment variables), so clients can enumerate supported providers instead of hardcoding them (#1075)

README.md

@@ -117,7 +117,9 @@ services:
     command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     restart: always

docker-compose.override.yml.example

@@ -14,5 +14,10 @@
 
 services:
   surrealdb:
-    ports:
+    # `!override` replaces the base file's port list instead of merging with
+    # it — without it, compose keeps both entries and the container fails to
+    # start with "port is already allocated". Requires Docker Compose
+    # v2.24.4+; on older clients, edit the ports entry in docker-compose.yml
+    # directly instead.
+    ports: !override
       - "8000:8000"

docs/0-START-HERE/quick-start-cloud.md

@@ -26,9 +26,11 @@ Create a new folder `open-notebook` and add this file:
 services:
   surrealdb:
     image: surrealdb/surrealdb:v2
-    command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
+    command: start --user root --pass password rocksdb:/mydata/mydatabase.db
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     # Removed the healthcheck because the v2 image is too minimal to run wget/curl

docs/0-START-HERE/quick-start-external-ollama.md

@@ -46,10 +46,12 @@ Create a new folder `open-notebook-external-ollama` and add these files:
 services:
   surrealdb:
     image: surrealdb/surrealdb:v2
-    command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
+    command: start --user root --pass password rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
 

docs/0-START-HERE/quick-start-local.md

@@ -33,10 +33,12 @@ Create a new folder `open-notebook-local` and add this file:
 services:
   surrealdb:
     image: surrealdb/surrealdb:v2
-    command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
+    command: start --user root --pass password rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
 

docs/0-START-HERE/quick-start-openai.md

@@ -23,9 +23,11 @@ Create a new folder `open-notebook` and add this file:
 services:
   surrealdb:
     image: surrealdb/surrealdb:v2
-    command: start --user root --pass password --bind 0.0.0.0:8000 rocksdb:/mydata/mydatabase.db
+    command: start --user root --pass password rocksdb:/mydata/mydatabase.db
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
 

docs/1-INSTALLATION/docker-compose.md

@@ -31,10 +31,20 @@ Create a file called `docker-compose.yml` with this content:
 services:
   surrealdb:
     image: surrealdb/surrealdb:v2
-    command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
+    # Credentials default to root:root for a zero-config local setup. Before
+    # exposing this instance to a network, set SURREAL_USER / SURREAL_PASSWORD
+    # in a .env file — they are applied here and to the open_notebook service
+    # below, so the two always stay in sync.
+    command: start --log info --user ${SURREAL_USER:-root} --pass ${SURREAL_PASSWORD:-root} rocksdb:/mydata/mydatabase.db
     user: root  # Required for bind mounts on Linux
     ports:
-      - "8000:8000"
+      # Localhost only: Open Notebook reaches the database over the internal
+      # compose network, so this host port exists purely for local debugging.
+      # The database uses default root credentials, so never publish it on
+      # 0.0.0.0. To reach it from another machine, use the opt-in override in
+      # docker-compose.override.yml.example (repo root) behind a firewall or
+      # SSH tunnel, with real SURREAL_USER / SURREAL_PASSWORD set.
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     environment:
@@ -51,10 +61,12 @@ services:
       # REQUIRED: Change this to your own secret string
       - OPEN_NOTEBOOK_ENCRYPTION_KEY=change-me-to-a-secret-string
 
-      # Database connection (default values - no need to change)
+      # Database connection. SURREAL_USER / SURREAL_PASSWORD default to
+      # root:root for local use; override them in a .env file before exposing
+      # the instance (the same values configure the surrealdb service above).
       - SURREAL_URL=ws://surrealdb:8000/rpc
-      - SURREAL_USER=root
-      - SURREAL_PASSWORD=root
+      - SURREAL_USER=${SURREAL_USER:-root}
+      - SURREAL_PASSWORD=${SURREAL_PASSWORD:-root}
       - SURREAL_NAMESPACE=open_notebook
       - SURREAL_DATABASE=open_notebook
     volumes:

docs/5-CONFIGURATION/advanced.md

@@ -164,7 +164,7 @@ Access API directly: `http://localhost:5056/docs`
 services:
   surrealdb:
     ports:
-      - "8001:8000"  # Change from 8000 to 8001
+      - "127.0.0.1:8001:8000"  # Change from 8000 to 8001 (localhost only)
     environment:
       - SURREAL_URL=ws://surrealdb:8001/rpc  # Update connection URL
 ```

docs/5-CONFIGURATION/database.md

@@ -33,6 +33,8 @@ SURREAL_NAMESPACE="open_notebook"
 SURREAL_DATABASE="open_notebook"
 ```
 
+> **Note:** If SurrealDB runs in Docker with its port published on `127.0.0.1` only (the documented default), it won't be reachable at your machine's IP. Re-publish the port deliberately — see `docker-compose.override.yml.example` in the repo root — behind a firewall or SSH tunnel, with real credentials set.
+
 ### Open Notebook and Surreal are running on the same machine
 
 If you are running both services locally or if you are using the deprecated [single container setup](../1-INSTALLATION/single-container.md)

docs/5-CONFIGURATION/openai-compatible.md

@@ -203,7 +203,10 @@ services:
     image: vllm/vllm-openai:latest
     command: --model meta-llama/Llama-3.1-8B-Instruct
     ports:
-      - "8000:8000"
+      # Localhost only (vLLM has no authentication by default), on host port
+      # 8001 because SurrealDB already publishes 8000. Open Notebook reaches
+      # vLLM over the compose network at http://vllm:8000/v1 regardless.
+      - "127.0.0.1:8001:8000"
     volumes:
       - ~/.cache/huggingface:/root/.cache/huggingface
     deploy:

docs/5-CONFIGURATION/reverse-proxy.md

@@ -424,7 +424,9 @@ services:
     image: surrealdb/surrealdb:latest
     command: start --log trace --user root --pass root file:/mydata/database.db
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
 ```

docs/7-DEVELOPMENT/development-setup.md

@@ -88,18 +88,19 @@ For local development, you can also use:
 ### Option A: Using Docker (Recommended)
 
 ```bash
-# Start SurrealDB in memory
-docker run -d --name surrealdb -p 8000:8000 \
+# Start SurrealDB in memory (publish the port on localhost only — the
+# database uses default credentials, so never publish it on 0.0.0.0)
+docker run -d --name surrealdb -p 127.0.0.1:8000:8000 \
   surrealdb/surrealdb:v2 start \
   --user root --pass password \
-  --bind 0.0.0.0:8000 memory
+  memory
 
 # Or with persistent storage
-docker run -d --name surrealdb -p 8000:8000 \
+docker run -d --name surrealdb -p 127.0.0.1:8000:8000 \
   -v surrealdb_data:/data \
   surrealdb/surrealdb:v2 start \
   --user root --pass password \
-  --bind 0.0.0.0:8000 file:/data/surreal.db
+  file:/data/surreal.db
 ```
 
 ### Option B: Using Make
@@ -333,7 +334,7 @@ git push origin feature/my-feature -f
 1. Check if SurrealDB is running: `docker ps | grep surrealdb`
 2. Verify URL in `.env`: Should be `ws://localhost:8000/rpc`
 3. Restart SurrealDB: `docker stop surrealdb && docker rm surrealdb`
-4. Then restart with: `docker run -d --name surrealdb -p 8000:8000 surrealdb/surrealdb:v2 start --user root --pass password --bind 0.0.0.0:8000 memory`
+4. Then restart with: `docker run -d --name surrealdb -p 127.0.0.1:8000:8000 surrealdb/surrealdb:v2 start --user root --pass password memory`
 
 ### "Address already in use"
 

docs/7-DEVELOPMENT/quick-start.md

@@ -37,7 +37,7 @@ In separate terminal windows:
 ```bash
 # Terminal 1: Start SurrealDB (database)
 make database
-# or: docker run -d --name surrealdb -p 8000:8000 surrealdb/surrealdb:v2 start --user root --pass password --bind 0.0.0.0:8000 memory
+# or: docker run -d --name surrealdb -p 127.0.0.1:8000:8000 surrealdb/surrealdb:v2 start --user root --pass password memory
 
 # Terminal 2: Start API (backend on port 5055)
 make api

examples/docker-compose-dev.yml

@@ -6,7 +6,9 @@ services:
     environment:
       - SURREAL_EXPERIMENTAL_GRAPHQL=true
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
     pull_policy: always
     user: root

examples/docker-compose-full-local.yml

@@ -31,7 +31,9 @@ services:
     command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     environment:

examples/docker-compose-ollama.yml

@@ -16,7 +16,9 @@ services:
     command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     environment:

examples/docker-compose-speaches.yml

@@ -27,7 +27,9 @@ services:
     command: start --log info --user root --pass root rocksdb:/mydata/mydatabase.db
     user: root
     ports:
-      - "8000:8000"
+      # Localhost only — the database uses default credentials, so never
+      # publish this port on 0.0.0.0
+      - "127.0.0.1:8000:8000"
     volumes:
       - ./surreal_data:/mydata
     environment: