Local Development

Run Graphora locally with zero-config mode or the full Docker stack.

Local Development

Graphora supports two local development modes: a zero-config mode that needs nothing except Python, and a full Docker stack for production-like environments.

Zero-Config Mode (Recommended for Getting Started)

Run the Graphora API with in-memory storage and no external dependencies. This is the fastest way to develop locally or evaluate the platform.

Prerequisites

• Python 3.11 or higher
• uv package manager
• An LLM API key (Gemini, OpenAI, or another supported provider)

1. Clone and install

   git clone https://github.com/graphora/graphora-api.git
   cd graphora-api
   uv sync
   
2. Configure environment

   cp .env.example .env
   

   Set these variables in your .env file:

   # Use in-memory storage (no Neo4j needed)
   STORAGE_TYPE=memory
   
   # Skip Clerk authentication for local dev
   AUTH_BYPASS_ENABLED=true
   
   # Provide at least one LLM API key
   GOOGLE_GEMINI_API_KEY=your-gemini-key
   # Or use OpenAI:
   # OPENAI_API_KEY=your-openai-key
   

   That is the minimum configuration. Redis, Neo4j, Postgres, and Prefect are all optional in this mode.

3. Start the server

   make dev
   

   The API will be available at http://localhost:8000.

4. Verify it works

   curl http://localhost:8000/health
   

What happens without Redis?

The progress tracker automatically falls back to an in-memory store when Redis is unavailable. You will see a log message like:

Redis unavailable (...), using in-memory progress tracking

This is expected in zero-config mode. Transform progress tracking works the same way — it just does not persist across server restarts.

In-memory mode stores all data in the running process. Data is lost when the server stops. Use this for development and testing only.

---

Full Docker Stack

For a production-like local environment with Neo4j, Redis, Postgres, and Prefect:

1. Copy environment templates

   cp .env.example .env
   

   The template includes the knobs used by docker compose (API port, Redis, Prefect, Neo4j container passwords). Populate the Clerk, Supabase, and provider keys you use in staging/production.

2. Launch the stack

   make compose-up
   

   Services:

   Service	Host endpoint	Notes
   API	http://localhost:${API_PORT:-8000}	Hot reload with /health and /ready endpoints
   Redis	internal only (redis://redis:6379/0)	No host port by default; override via docker-compose.override.yml
   Prefect	http://localhost:${PREFECT_PORT:-4200}	PREFECT_API_URL is injected into the API container
   Neo4j	bolt://localhost:7687	For graph storage
   Postgres	localhost:5432	Application database for configs and audit logs

3. Start the API

   make dev
   
4. Check health

   curl http://localhost:8000/health
   curl http://localhost:8000/ready
   

   /health returns immediately once FastAPI starts. /ready pings Redis and the Prefect API so docker-compose health checks know when the stack is usable.

5. Daily commands

   make compose-logs     # tail service output
   make compose-status   # show container status
   make compose-down     # stop and remove containers + volumes
   

---

Storage Modes

Graphora supports two storage backends, controlled by the STORAGE_TYPE environment variable:

Mode	Value	Database Required	Best For
In-memory	STORAGE_TYPE=memory	No	Local dev, demos, testing
Neo4j	STORAGE_TYPE=neo4j	Yes	Production, staging

When using STORAGE_TYPE=memory, all graph data is stored in the running process and is lost when the server stops. For production use, always use STORAGE_TYPE=neo4j with a properly configured Neo4j instance.

---

Authentication Modes

Mode	Configuration	Best For
Bypassed	AUTH_BYPASS_ENABLED=true	Local development
Clerk	Clerk env vars configured	Production, staging

When auth bypass is enabled, all requests are treated as coming from the user specified by AUTH_BYPASS_USER_ID (defaults to local-dev-user). Never enable auth bypass in production.

---

Frontend

Start the graphora-fe app separately:

cd graphora-fe
npm install
npm run dev

Point NEXT_PUBLIC_API_URL (or BACKEND_API_URL) to http://localhost:8000.

---

Tips

• Use make dev-up -- --build whenever Dockerfile dependencies change.
• Run make openapi-snapshot before syncing docs so the Mintlify API reference stays current.
• For the full list of Make targets, run make help.
• See Configuration for a complete reference of all environment variables.