> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphora.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://github.com/astral-sh/uv) package manager
* An LLM API key (Gemini, OpenAI, or another supported provider)

<Steps>
  <Step title="Clone and install">
    ```bash theme={null}
    git clone https://github.com/graphora/graphora-api.git
    cd graphora-api
    uv sync
    ```
  </Step>

  <Step title="Configure environment">
    ```bash theme={null}
    cp .env.example .env
    ```

    Set these variables in your `.env` file:

    ```bash theme={null}
    # 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.
  </Step>

  <Step title="Start the server">
    ```bash theme={null}
    make dev
    ```

    The API will be available at `http://localhost:8000`.
  </Step>

  <Step title="Verify it works">
    ```bash theme={null}
    curl http://localhost:8000/health
    ```
  </Step>
</Steps>

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

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

***

## Full Docker Stack

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

<Steps>
  <Step title="Copy environment templates">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Launch the stack">
    ```bash theme={null}
    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                     |
  </Step>

  <Step title="Start the API">
    ```bash theme={null}
    make dev
    ```
  </Step>

  <Step title="Check health">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Daily commands">
    ```bash theme={null}
    make compose-logs     # tail service output
    make compose-status   # show container status
    make compose-down     # stop and remove containers + volumes
    ```
  </Step>
</Steps>

***

## 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](https://github.com/graphora/graphora-fe) app separately:

```bash theme={null}
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](/platform/configuration) for a complete reference of all environment variables.