Bring server/'s docs in line with this fork's mandatory auth

server/.env.example

@@ -1,6 +1,36 @@
+# Copy to server/.env to run the API from this directory with uvicorn. Deploying to Render
+# instead? The root .env.example and README cover that; nothing here is read by render.yaml.
+#
+# Optional settings stay commented out rather than assigned an empty value: '' is not the same
+# as unset, and arrives at the app as a real setting.
+
+# --- Required ---------------------------------------------------------------------
+# Graphiti calls an LLM to extract entities and facts. https://platform.openai.com/api-keys
 OPENAI_API_KEY=
-NEO4J_PORT=7687
-# Only used if not running a neo4j container in docker
+
+# Bearer token required by every endpoint except /healthcheck. Startup fails without it, so
+# there is no unauthenticated mode to fall into. Must be 16+ printable-ASCII characters.
+# Any local-only placeholder will do; this one matches what docker-compose.yml defaults to.
+GRAPHITI_API_KEY=insecure-local-dev-key
+
+# --- Graph backend ----------------------------------------------------------------
+# 'neo4j' (the default) or 'falkordb'.
+DB_BACKEND=neo4j
+
+# Neo4j, used when DB_BACKEND=neo4j.
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
-NEO4J_PASSWORD=password
+NEO4J_PASSWORD=password
+# Bolt port; read by docker-compose.yml, which defaults it to 7687.
+NEO4J_PORT=7687
+
+# FalkorDB, used instead of the Neo4j block when DB_BACKEND=falkordb.
+# FALKORDB_HOST=localhost
+# FALKORDB_PORT=6379
+# FALKORDB_DATABASE=default_db
+
+# --- Model ------------------------------------------------------------------------
+# Any OpenAI model id; leave unset to use graphiti-core's default.
+# MODEL_NAME=
+# Embedding model; leave unset for graphiti-core's default (text-embedding-3-small).
+# EMBEDDING_MODEL_NAME=

server/README.md

@@ -2,77 +2,97 @@
 
 Graph service is a fast api server implementing the [graphiti](https://github.com/getzep/graphiti) package.
 
-## Container Releases
+**Deploying to Render?** Start at the [root README](../README.md) — it covers the one-click
+Blueprint, the FalkorDB pairing, and the env vars `render.yaml` sets for you. This file is only
+about running the API on its own.
+
+## Authentication
 
-The FastAPI server container is automatically built and published to Docker Hub when a new `graphiti-core` version is released to PyPI.
+Every endpoint except `/healthcheck` requires a bearer token, and there is no way to switch that
+off: `GRAPHITI_API_KEY` must be set to at least 16 printable-ASCII characters or the server exits
+at startup. That is deliberate — the API writes to a shared graph and spends the deployment's
+`OPENAI_API_KEY`, and an open service and one that 401s everything both look healthy to a health
+check.
 
-**Image:** `zepai/graphiti`
+```
+Authorization: Bearer <GRAPHITI_API_KEY>
+```
 
-**Available tags:**
-- `latest` - Latest stable release
-- `0.22.1` - Specific version (matches graphiti-core version)
+`/docs`, `/redoc` and `/openapi.json` stay public so Swagger UI is browsable; use its
+**Authorize** button to call anything. A wrong or missing key gets `401`, and after 10 rejections
+in a minute the server answers `429` instead.
 
-**Platforms:** linux/amd64, linux/arm64
+## Container Releases
 
-The automated release workflow:
-1. Triggers when `graphiti-core` PyPI release completes
-2. Waits for PyPI package availability
-3. Builds multi-platform Docker image
-4. Tags with version number and `latest`
-5. Pushes to Docker Hub
+Upstream publishes the FastAPI server to Docker Hub as `zepai/graphiti` when a new
+`graphiti-core` version is released to PyPI (linux/amd64 and linux/arm64, tagged `latest` and by
+version; pre-releases are skipped).
 
-Only stable releases are built automatically (pre-release versions are skipped).
+**That image is upstream's and does not include this fork's authentication**, so it is not what
+the instructions below use. Build from this repo's root `Dockerfile` instead — that is also what
+`render.yaml` and `docker-compose.yml` do, so all three stay in step on one `graphiti-core` pin.
 
 ## Running Instructions
 
 1. Ensure you have Docker and Docker Compose installed on your system.
 
-2. Add `zepai/graphiti:latest` to your service setup
+2. Copy [`.env.example`](.env.example) to `server/.env` and fill in `OPENAI_API_KEY`.
 
-3. Make sure to pass the following environment variables to the service
+3. The quickest path is the compose stack in the repo root, which builds this service and starts a
+   database beside it:
 
-   ```
-   OPENAI_API_KEY=your_openai_api_key
-   NEO4J_USER=your_neo4j_user
-   NEO4J_PASSWORD=your_neo4j_password
-   NEO4J_PORT=your_neo4j_port
+   ```bash
+   docker compose up                      # API on :8000 with Neo4j
+   docker compose --profile falkordb up   # API on :8001 with FalkorDB, mirroring render.yaml
    ```
 
-4. This service depends on having access to a neo4j instance, you may wish to add a neo4j image to your service setup as well. Or you may wish to use neo4j cloud or a desktop version if running this locally.
+   It defaults `GRAPHITI_API_KEY` to `insecure-local-dev-key`, so the examples in the root README
+   work unchanged.
 
-   An example of docker compose setup may look like this:
+4. To wire it into your own compose file, build from the repo root and pass the variables below.
+   This service needs access to a Neo4j instance — add a Neo4j image beside it as here, or point
+   `NEO4J_URI` at Neo4j Aura or a desktop install.
 
    ```yml
-      version: '3.8'
-
-      services:
-      graph:
-         image: zepai/graphiti:latest
-         ports:
-            - "8000:8000"
-
-         environment:
-            - OPENAI_API_KEY=${OPENAI_API_KEY}
-            - NEO4J_URI=bolt://neo4j:${NEO4J_PORT}
-            - NEO4J_USER=${NEO4J_USER}
-            - NEO4J_PASSWORD=${NEO4J_PASSWORD}
-      neo4j:
-         image: neo4j:5.22.0
-
-         ports:
-            - "7474:7474"  # HTTP
-            - "${NEO4J_PORT}:${NEO4J_PORT}"  # Bolt
-         volumes:
-            - neo4j_data:/data
-         environment:
-            - NEO4J_AUTH=${NEO4J_USER}/${NEO4J_PASSWORD}
-
-      volumes:
-      neo4j_data:
+   services:
+     graph:
+       build:
+         context: .          # the repo root, not server/
+       # Bound to 127.0.0.1, because the key below is a committed placeholder and protects
+       # nothing. Drop the prefix to reach this from another host, and set a real key in the
+       # same edit.
+       ports:
+         - "127.0.0.1:8000:8000"
+       environment:
+         - OPENAI_API_KEY=${OPENAI_API_KEY}
+         # Required. Startup fails without it; 16+ printable-ASCII characters.
+         - GRAPHITI_API_KEY=${GRAPHITI_API_KEY:-insecure-local-dev-key}
+         - NEO4J_URI=bolt://neo4j:${NEO4J_PORT:-7687}
+         - NEO4J_USER=${NEO4J_USER:-neo4j}
+         - NEO4J_PASSWORD=${NEO4J_PASSWORD:-password}
+     neo4j:
+       image: neo4j:5.26.2
+       # Localhost-bound as above, with more at stake: the password defaults to `password` and
+       # Bolt is unmediated write access.
+       ports:
+         - "127.0.0.1:7474:7474"                              # HTTP
+         - "127.0.0.1:${NEO4J_PORT:-7687}:${NEO4J_PORT:-7687}" # Bolt
+       volumes:
+         - neo4j_data:/data
+       environment:
+         - NEO4J_AUTH=${NEO4J_USER:-neo4j}/${NEO4J_PASSWORD:-password}
+
+   volumes:
+     neo4j_data:
    ```
 
-5. Once you start the service, it will be available at `http://localhost:8000` (or the port you have specified in the docker compose file).
+5. Once you start the service, it will be available at `http://localhost:8000` (or the port you
+   have specified in the docker compose file). `GET /healthcheck` is the one endpoint that takes
+   no key.
 
-6. You may access the swagger docs at `http://localhost:8000/docs`. You may also access redocs at `http://localhost:8000/redoc`.
+6. You may access the swagger docs at `http://localhost:8000/docs`. You may also access redocs at
+   `http://localhost:8000/redoc`. Click **Authorize** and paste your `GRAPHITI_API_KEY` before
+   using **Try it out**.
 
-7. You may also access the neo4j browser at `http://localhost:7474` (the port depends on the neo4j instance you are using).
+7. You may also access the neo4j browser at `http://localhost:7474` (the port depends on the neo4j
+   instance you are using).