Skip to main content

​
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. 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

2

Configure environment

Set these variables in your .env file:
That is the minimum configuration. Redis, Neo4j, Postgres, and Prefect are all optional in this mode.
3

Start the server

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

Verify it works

​
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:
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

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

Services:
3

Start the API

4

Check health

/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

​
Storage Modes

Graphora supports two storage backends, controlled by the STORAGE_TYPE environment variable: 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

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:
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.