fix: stop production overlays defaulting to third-party LLM and online GeoIP (#607)

.env.example

@@ -141,8 +141,16 @@ STUCK_FILE_RECONCILIATION_ENABLED=true
 STUCK_FILE_TIMEOUT_MINUTES=30
 
 # LLM Configuration (Local LLM Server)
-# Use a local LLM server (LM Studio, Ollama) or OpenAI API
-LLM_API_BASE_URL=http://localhost:1234/v1
+# Point this at a locally-hosted inference server (LM Studio, Ollama, vLLM). Prompts are built
+# from analysed capture content, so this endpoint is a data egress path — TracePcap is intended
+# to run fully offline and should not be pointed at an internet-hosted provider.
+#
+# REQUIRED by both production overlays: they abort rather than inherit a default, so the endpoint
+# is always a deliberate choice. See docs/operations/production-hardening.rst.
+#
+# Use the inference host's address as reachable FROM THE BACKEND CONTAINER — `localhost` resolves
+# to the container itself, not to a server on the host or LAN.
+LLM_API_BASE_URL=http://<your-inference-host>:1234/v1
 LLM_API_KEY=
 LLM_MODEL=Qwen2.5-14B-Coder-Instruct
 LLM_TEMPERATURE=0.7

docker-compose.offline-prod.yml

@@ -88,6 +88,14 @@ services:
       DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env — see .env.example}
       MINIO_ACCESS_KEY: ${MINIO_ROOT_USER:?set MINIO_ROOT_USER in .env — see .env.example}
       MINIO_SECRET_KEY: ${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env — see .env.example}
+      # Data egress. REQUIRED, matching docker-compose.prod.yml. The base offline file defaults
+      # this to http://localhost:1234/v1, which resolves to the *backend container itself*, not to
+      # any inference host on the network — so inheriting it would leave Story mode and Network
+      # Insights failing at request time with a connection error instead of at startup.
+      LLM_API_BASE_URL: ${LLM_API_BASE_URL:?set LLM_API_BASE_URL in .env (e.g. http://<host>:1234/v1) — see .env.example}
+      # Restated so an air-gapped deployment's guarantee doesn't rest on a default in the file
+      # below it. Left overridable: a deployment with internet access may opt back in.
+      GEO_FORCE_OFFLINE: ${GEO_FORCE_OFFLINE:-true}
       # Public issuer (matches the token `iss`). Must equal PUBLIC_URL + /realms/tracepcap.
       KEYCLOAK_ISSUER_URI: ${PUBLIC_URL:-http://localhost:8888}/realms/tracepcap
       # Backend-reachable JWKS endpoint (internal docker network), fetched lazily so the

docker-compose.prod.yml

@@ -85,6 +85,15 @@ services:
       DATABASE_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD in .env — see .env.example}
       MINIO_ACCESS_KEY: ${MINIO_ROOT_USER:?set MINIO_ROOT_USER in .env — see .env.example}
       MINIO_SECRET_KEY: ${MINIO_ROOT_PASSWORD:?set MINIO_ROOT_PASSWORD in .env — see .env.example}
+      # Data egress. The base file defaults the LLM to api.openai.com for convenience in local
+      # dev; inheriting that here would send capture-derived prompts (Story mode, Network
+      # Insights) to a third party from the deployment most likely to hold real operational data.
+      # REQUIRED, so the endpoint is always a deliberate choice — point it at a local inference
+      # server (LM Studio, Ollama, vLLM) for an offline deployment.
+      LLM_API_BASE_URL: ${LLM_API_BASE_URL:?set LLM_API_BASE_URL in .env (e.g. http://<host>:1234/v1) — see .env.example}
+      # Resolve GeoIP from the bundled MMDB instead of probing ipinfo.io at runtime, matching
+      # docker-compose.offline.yml. Set GEO_FORCE_OFFLINE=false to opt back into online lookups.
+      GEO_FORCE_OFFLINE: ${GEO_FORCE_OFFLINE:-true}
       # Public issuer (matches the token `iss`). Must equal PUBLIC_URL + /realms/tracepcap.
       KEYCLOAK_ISSUER_URI: ${PUBLIC_URL:-http://localhost:8888}/realms/tracepcap
       # Backend-reachable JWKS endpoint (internal docker network). Decouples key fetch from the

docs/operations/production-hardening.rst

@@ -242,8 +242,32 @@ To stop a service and have it *stay* stopped, use ``docker compose stop <svc>``;
 Configure LLM Privacy
 ---------------------
 
-If you use AI features, ensure ``LLM_API_BASE_URL`` points to a locally-hosted
-model. Do **not** configure a cloud API endpoint if your PCAP data is sensitive.
+AI features (Story mode, Network Insights) build their prompts from analysed
+capture content, so the LLM endpoint is a **data egress path**.
+
+Both production overlays **require** ``LLM_API_BASE_URL`` and abort if it is
+unset, rather than falling back to a default — the online overlay would otherwise
+inherit ``api.openai.com`` from the base file, and the offline overlay
+``localhost``. Point it at a locally-hosted inference server (LM Studio, Ollama,
+vLLM):
+
+.. code-block:: bash
+
+   LLM_API_BASE_URL=http://<your-inference-host>:1234/v1
+
+.. warning::
+
+   Use the address of the inference host **as reachable from the backend
+   container**. ``localhost`` resolves to the container itself, not to a server
+   running on the Docker host or elsewhere on the LAN, so it will fail at request
+   time rather than at startup.
+
+Do **not** configure a cloud API endpoint if your PCAP data is sensitive.
+
+The production overlays also default ``GEO_FORCE_OFFLINE`` to ``true``, resolving
+geolocation from the bundled DB-IP Lite MMDB instead of probing ``ipinfo.io`` at
+runtime. Set ``GEO_FORCE_OFFLINE=false`` only if outbound lookups are acceptable
+and the deployment has internet access.
 
 Restrict MinIO Console Access
 -------------------------------