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

Deploy the GraphRAG Agent by cloning the repository, installing Python dependencies from requirements.txt, configuring environment variables in .env, optionally starting Neo4j via Docker Compose, and launching both the FastAPI backend (server/main.py) and Streamlit frontend (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:

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:

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

pip install -r requirements.txt

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

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:

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:

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:

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

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

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}