# How to Set Up HugeGraph AI for Local Development: Docker and Source Installation Guide

> Easily set up HugeGraph AI locally with Docker Compose or source installation. Access the RAG service at http://localhost:8001 and accelerate your AI development.

- Repository: [The Apache Software Foundation/incubator-hugegraph-ai](https://github.com/apache/incubator-hugegraph-ai)
- Tags: getting-started
- Published: 2026-02-24

---

**You can set up HugeGraph AI locally using either Docker Compose for a quick containerized deployment or source installation with the `uv` package manager for full development control, accessing the RAG service at `http://localhost:8001`.**

HugeGraph AI integrates the **HugeGraph** graph database with large language model (LLM) capabilities through a multi-module Python workspace. This guide walks you through configuring the **apache/incubator-hugegraph-ai** repository for local development, whether you prefer containerized services or a native Python environment with IDE debugging support.

## Prerequisites

Before setting up HugeGraph AI, ensure you have the following tools installed:

- **Python 3.10+** (tested and supported)
- **Docker** (optional but recommended for containerized services)
- **uv package manager** (version 0.7+)
- **Git**

Install `uv` if it is not already present:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

```

## Clone the Repository

Start by cloning the official repository and navigating to the project root:

```bash
git clone https://github.com/apache/incubator-hugegraph-ai.git
cd incubator-hugegraph-ai

```

The project organizes code into four main modules: `hugegraph-llm/` for LLM-RAG services, `hugegraph-ml/` for graph algorithms, `hugegraph-python-client/` for REST API access, and `vermeer-python-client/` for graph computing.

## Choose Your Installation Method

### Option A: Docker Compose (Recommended for Quick Start)

Docker Compose boots both the HugeGraph server and the RAG service together using the configuration in [`docker/docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker/docker-compose-network.yml).

First, copy the environment template and set your absolute project path:

```bash
cp docker/env.template docker/.env
sed -i "s|path_to_project|$(pwd)|" docker/.env

```

Start the services:

```bash
docker compose -f docker/docker-compose-network.yml up -d

```

Verify the containers are healthy:

```bash
docker compose -f docker/docker-compose-network.yml ps

```

After startup, the **HugeGraph server** is available at `http://localhost:8080` and the **RAG service** (FastAPI + Gradio UI) runs at `http://localhost:8001`.

### Option B: Source Installation (Full Control and IDE Debugging)

For development work requiring breakpoints and custom modifications, install from source:

1. Start a standalone HugeGraph container (required only once):

```bash
docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph

```

2. Install project dependencies using `uv`, which automatically creates a `.venv`:

```bash
uv sync --extra llm

```

Use `uv sync --all-extras` to install all module dependencies, or add `--extra vectordb` if you need Milvus or Qdrant support.

3. Activate the virtual environment:

```bash
source .venv/bin/activate

```

4. Launch the demo application:

```bash
python -m hugegraph_llm.demo.rag_demo.app

```

The web interface opens at `http://127.0.0.1:8001`.

## Configure Environment Variables

Whether using Docker or source installation, configuration resides in the `.env` file (generated from `docker/env.template`). Key variables include:

- `HUGEGRAPH_HOST` and `HUGEGRAPH_PORT` for server connection
- `LANGUAGE` (set to `EN` or `CN` to switch prompt languages)
- `LLM_PROVIDER` and provider tokens like `OPENAI_API_KEY`

The system uses **LiteLLM** under the hood for provider abstraction. Edit `hugegraph-llm/.env` directly when running from source, or modify `docker/.env` for Docker deployments.

## Using the Scheduler Programmatically

Once the environment is running, interact with workflows directly through Python instead of the web UI. The `SchedulerSingleton` in [`hugegraph-llm/src/hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/flows/scheduler.py) serves as the central entry point, caching `GPipelines` for efficiency.

```python
from hugegraph_llm.flows.scheduler import SchedulerSingleton

# Example: Graph-only RAG query

scheduler = SchedulerSingleton.get_instance()
result = scheduler.schedule_flow(
    "rag_graph_only",
    query="Tell me about the movie Inception.",
    graph_only_answer=True,
    vector_only_answer=False,
    raw_answer=False,
    gremlin_tmpl_num=-1,
    gremlin_prompt=None,
)
print(result.get("graph_only_answer"))

```

Other available flows include `rag_vector_only`, `text2gremlin`, and `build_examples_index`, each constructing specific pipelines like `RAGGraphOnlyFlow` or `Text2GremlinFlow` internally.

## Testing and Code Quality

Validate your setup by running the test suites for each module:

```bash
cd hugegraph-llm && pytest
cd ../hugegraph-python-client && pytest
cd ../hugegraph-ml && pytest

```

Format code and run linting using the provided script:

```bash
./style/code_format_and_analysis.sh

```

This executes `ruff` and pre-commit hooks across the codebase.

## Key Source Files for Developers

| File | Purpose |
|------|---------|
| `docker/env.template` | Base environment configuration template copied to `.env` |
| [`docker/docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker/docker-compose-network.yml) | Docker network and service orchestration |
| [`hugegraph-llm/src/hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/flows/scheduler.py) | Central scheduler implementing `SchedulerSingleton` |
| [`hugegraph-llm/src/hugegraph_llm/demo/rag_demo/app.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/demo/rag_demo/app.py) | FastAPI entry point hosting the Gradio UI |
| [`hugegraph-llm/src/hugegraph_llm/config/config_data.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/config/config_data.py) | Default schema templates for the UI |
| [`hugegraph-llm/README.md`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/README.md) | High-level documentation and usage examples |

## Summary

- **HugeGraph AI** requires Python 3.10+, Docker, and the `uv` package manager for local development.
- **Docker Compose** in [`docker/docker-compose-network.yml`](https://github.com/apache/incubator-hugegraph-ai/blob/main/docker/docker-compose-network.yml) provides the fastest setup, binding ports 8080 (graph server) and 8001 (RAG UI).
- **Source installation** uses `uv sync --extra llm` to create a virtual environment and `python -m hugegraph_llm.demo.rag_demo.app` to start services.
- Configuration happens through `.env` files derived from `docker/env.template`, controlling LLM providers, language settings, and database connections.
- The **SchedulerSingleton** class in [`hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/flows/scheduler.py) enables programmatic execution of RAG and Gremlin-generation workflows.

## Frequently Asked Questions

### What is the difference between the Docker and source installation methods?

Docker Compose runs the HugeGraph server and RAG service in containers with minimal local setup, ideal for testing. Source installation creates a local Python virtual environment via `uv`, giving you full control over dependencies and enabling IDE debugging of the FastAPI application in [`hugegraph_llm/demo/rag_demo/app.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph_llm/demo/rag_demo/app.py).

### How do I connect to a different LLM provider?

Edit the `LLM_PROVIDER` variable in your `.env` file and add the corresponding API key (e.g., `OPENAI_API_KEY`). The project uses LiteLLM for provider routing, so any LiteLLM-supported backend works without code changes.

### Can I use HugeGraph AI without Docker?

Yes. Run a standalone HugeGraph server using `docker run -itd --name=server -p 8080:8080 hugegraph/hugegraph`, then use `uv sync --extra llm` to install Python dependencies locally. This hybrid approach keeps the graph database containerized while running the Python RAG service natively for development.

### Where is the pipeline scheduling logic implemented?

The scheduling logic resides in [`hugegraph-llm/src/hugegraph_llm/flows/scheduler.py`](https://github.com/apache/incubator-hugegraph-ai/blob/main/hugegraph-llm/src/hugegraph_llm/flows/scheduler.py). The `SchedulerSingleton` class manages `GPipeline` construction and caching, exposing the `schedule_flow()` method to execute specific workflows like `rag_graph_only` or `text2gremlin` programmatically.