Expose a runnable backend without giving the ingress layer secrets

The backend can now be inspected through a loopback-only gateway while the database-aware API remains on the internal data network. A governed synthetic demo proves readiness, pgvector retrieval, reranking, and citation output through real HTTP without invoking cloud models.

Constraint: The previously exposed Bailian key is compromised and cannot be used for live validation

Constraint: The API must be locally reachable while retaining no internet egress

Rejected: Attach the API directly to the ingress network | a real socket test proved that configuration still had egress

Rejected: Publish a port from the internal-only network | Docker Desktop did not expose the host port

Confidence: high

Scope-risk: moderate

Reversibility: clean

Directive: Keep model and database credentials out of the gateway; do not relax the fixed demo identity/profile filters

Tested: make verify; 63 pytest tests; strict mypy; Ruff; Secret scan; Compose config; three backend image builds; API/DB/gateway healthy; migration exit 0; Swagger browser check; live/ready/meta/status/search HTTP; 20/20/20 index; API egress ENETUNREACH; empty gateway mounts and business environment

Not-tested: Live Bailian calls require a newly rotated key; full generated-answer flow and React UI are not implemented

backend/app/main.py

@@ -1,39 +1,51 @@
-"""Minimal FastAPI entrypoint; product endpoints are added in stage 2."""
+"""FastAPI entrypoint with dependency-free liveness and database readiness probes."""
 
 from typing import Any
 
 import psycopg
 import uvicorn
-from fastapi import FastAPI, HTTPException, status
+from fastapi import FastAPI, Response, status
 
 from app import __version__
+from app.api.v1 import demo_router
 from app.core.config import get_settings
 from app.core.secrets import SecretFileError
 
 app = FastAPI(title="Geological RAG API", version=__version__)
+app.include_router(demo_router)
+
+type HealthPayload = dict[str, str | dict[str, str]]
 
 
+@app.get("/health/live", tags=["health"])
 @app.get("/api/v1/health/live", tags=["health"])
 def live() -> dict[str, str]:
     return {"status": "ok", "version": __version__}
 
 
+@app.get(
+    "/health/ready",
+    tags=["health"],
+    responses={status.HTTP_503_SERVICE_UNAVAILABLE: {"description": "Database unavailable"}},
+)
 @app.get("/api/v1/health/ready", tags=["health"])
-def ready() -> dict[str, str]:
+def ready(response: Response) -> HealthPayload:
     settings = get_settings()
     try:
         dsn = settings.database_url().set(drivername="postgresql")
         with psycopg.connect(
             dsn.render_as_string(hide_password=False),
             connect_timeout=2,
+            autocommit=True,
         ) as connection:
-            connection.execute("SELECT 1")
-    except (OSError, SecretFileError, psycopg.Error) as exc:
-        raise HTTPException(
-            status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
-            detail="database unavailable",
-        ) from exc
-    return {"status": "ready"}
+            result = connection.execute("SELECT 1").fetchone()
+            if result != (1,):
+                raise psycopg.DatabaseError("readiness query returned an unexpected result")
+    except (OSError, SecretFileError, psycopg.Error):
+        # Do not expose connection strings, secret paths, hostnames, or driver errors.
+        response.status_code = status.HTTP_503_SERVICE_UNAVAILABLE
+        return {"status": "not_ready", "checks": {"database": "unavailable"}}
+    return {"status": "ready", "checks": {"database": "ok"}}
 
 
 @app.get("/api/v1/meta", tags=["meta"])
@@ -52,5 +64,5 @@ def meta() -> dict[str, Any]:
 
 
 if __name__ == "__main__":
-    # Container ingress is controlled by Compose; only the edge proxy publishes a port.
+    # Compose publishes this listener only on the host loopback interface.
     uvicorn.run("app.main:app", host="0.0.0.0", port=8000)  # noqa: S104