# GraphRAG Agent Deployment: Complete Steps to Deploy the Services Locally or with Docker

> Deploy the GraphRAG Agent locally or with Docker. Follow our complete guide to clone the repo install dependencies configure environment variables and launch backend and frontend services.

- Repository: [GLK/graph-rag-agent](https://github.com/1517005260/graph-rag-agent)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Deploy the GraphRAG Agent by cloning the repository, installing Python dependencies from [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt), configuring environment variables in `.env`, optionally starting Neo4j via Docker Compose, and launching both the FastAPI backend ([`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py)) and Streamlit frontend ([`frontend/app.py`](https://github.com/1517005260/graph-rag-agent/blob/main/frontend/app.py)).**

The GraphRAG Agent is a modular Python project maintained in the `1517005260/graph-rag-agent` repository that combines a FastAPI backend with a Streamlit UI to perform retrieval-augmented generation over knowledge graphs. Understanding the correct deployment steps ensures the graph database, LLM connections, and web interface initialize properly. Below is a complete walkthrough of the GraphRAG Agent deployment process, referencing specific source files and commands required to run the services.

## Step-by-Step GraphRAG Agent Deployment

### Clone the Repository

Start by cloning the source code and navigating into the project directory:

```bash
git clone https://github.com/1517005260/graph-rag-agent.git
cd graph-rag-agent

```

The repository layout and general project overview are documented in the root **readme.md** file.

### Install Python Dependencies

Create an isolated virtual environment and install the required packages listed in [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt):

```bash
python -m venv .venv
source .venv/bin/activate          # On Windows: .venv\Scripts\activate

pip install -r requirements.txt

```

The [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt) file contains all necessary Python dependencies for the FastAPI server, Streamlit interface, and graph processing libraries.

### Configure Environment Variables

Copy the example environment template and populate it with your credentials:

```bash
cp .env.example .env

# Edit .env with your Neo4j URI, OpenAI API key, and other secrets

```

The **.env.example** template specifies required variables including `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD`, and `OPENAI_API_KEY`. The application reads these at runtime to connect to the graph database and LLM providers.

### Start Supporting Services with Docker Compose

If you require a local Neo4j instance (and optional vector store), start the supporting infrastructure:

```bash
docker-compose up -d

```

The **docker-compose.yaml** file defines the Neo4j database service and any additional containers needed for the graph backend. This step is optional if you already have a remote Neo4j instance configured in your `.env` file.

### Launch the FastAPI Backend

Start the ASGI server using Uvicorn with the application entry point defined in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py):

```bash
uvicorn server.main:app --reload

```

The **server/main.py** file creates the FastAPI `app` object, registers API routes, and exposes the health check endpoint at `http://127.0.0.1:8000/health`. The backend automatically loads configuration from the `.env` file to establish connections to Neo4j and LLM services.

### Start the Streamlit Frontend

In a separate terminal (with the virtual environment activated), launch the web interface:

```bash
streamlit run frontend/app.py

```

The **frontend/app.py** script initializes the Streamlit UI, while **frontend/utils/api.py** contains the helper functions that handle HTTP communication between the frontend and the FastAPI backend.

### Verify the Deployment

Confirm the services are operational by checking the following endpoints:

- **Backend Health**: Navigate to `http://127.0.0.1:8000/health` or use the `/health` route implemented in [`server/main.py`](https://github.com/1517005260/graph-rag-agent/blob/main/server/main.py)
- **Streamlit UI**: Open `http://localhost:8501` in your browser to access the chat interface

Once verified, you can submit RAG queries through the UI or programmatically via the FastAPI routes.

## Automated Deployment Script

For convenience, you can automate the entire GraphRAG Agent deployment using a bash script:

```bash
#!/usr/bin/env bash
set -e

# Install dependencies

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# Configure environment

cp .env.example .env
echo "Edit .env with your credentials before proceeding"

# Start infrastructure

docker-compose up -d

# Start backend in background

uvicorn server.main:app --reload &

# Start frontend

streamlit run frontend/app.py

```

## Summary

- **Clone** the `1517005260/graph-rag-agent` repository and install dependencies from [`requirements.txt`](https://github.com/1517005260/graph-rag-agent/blob/main/requirements.txt) into a Python virtual environment
- **Configure** the `.env` file based on the `.env.example` template, ensuring `NEO4J_URI` and `OPENAI_API_KEY` are set
- **Orchestrate** supporting services (Neo4j) using `docker-compose up -d` as defined in **docker-compose.yaml**
- **Launch** the FastAPI backend with `uvicorn server.main:app --reload` and the Streamlit frontend with `streamlit run frontend/app.py`
- **Verify** deployment via the `/health` endpoint and the Streamlit interface at `localhost:8501`

## Frequently Asked Questions

### What are the hardware requirements for GraphRAG Agent deployment?

The GraphRAG Agent requires a machine capable of running Python 3.8+ and Docker (if using the included Neo4j container). Minimum specifications include 4GB RAM for local development, though production deployments with large knowledge graphs should allocate additional memory for the Neo4j instance and LLM API processing.

### Can I deploy GraphRAG Agent without Docker?

Yes, Docker is only required for the supporting Neo4j database defined in **docker-compose.yaml**. If you have an existing Neo4j instance (local or cloud-hosted), simply configure the connection details in your `.env` file and skip the `docker-compose` step. The FastAPI backend and Streamlit frontend run as standard Python processes.

### How do I verify the backend is running correctly?

The FastAPI application exposes a health check endpoint at `http://127.0.0.1:8000/health` as implemented in **server/main.py**. A successful response indicates the server is operational and environment variables are loaded. You can also test the RAG functionality using the example Python client provided in the repository documentation.

### Which environment variables are required for deployment?

The **.env.example** file lists all required variables, including `NEO4J_URI`, `NEO4J_USER`, `NEO4J_PASSWORD` for graph database connectivity, and `OPENAI_API_KEY` (or equivalent) for LLM access. The application will fail to start if these critical connection parameters are missing from the `.env` file in the project root.