getting-started.md

Getting Started

This guide walks you through installing ForgeRAG, running it locally, and ingesting your first document.

Prerequisites

Requirement	Version	Notes
Python	3.10+	3.11 recommended
Node.js	18+	Only needed for building the frontend
pip	latest	pip install --upgrade pip

You also need an API key for at least one LLM provider (OpenAI, DeepSeek, Cohere, etc.) or a local Ollama instance.

Installation

1. Clone the repository

git clone https://github.com/deeplethe/ForgeRAG.git
cd ForgeRAG

2. Create a virtual environment

python -m venv .venv

# Linux / macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

3. Install Python dependencies

pip install -r requirements.txt

The base requirements.txt includes only the core dependencies. Optional backends need extra packages:

Backend	Extra packages	Install command
PostgreSQL	psycopg[binary]	pip install "psycopg[binary]>=3.1"
pgvector	psycopg[binary]	(same as above)
MySQL	pymysql	pip install "pymysql>=1.1"
Neo4j	neo4j	pip install "neo4j>=5.0"
S3 storage	boto3	pip install "boto3>=1.34"
Alibaba OSS	oss2	pip install "oss2>=2.18"
Local embeddings	sentence-transformers	pip install "sentence-transformers>=3.0"
MinerU parser	mineru	pip install mineru

4. Build the frontend

cd web
npm install
npm run build
cd ..

The built files are placed in web/dist/ and served automatically by the backend.

5. Set your API key

# Linux / macOS
export OPENAI_API_KEY=sk-...

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

Or copy .env.example to .env and fill in your key:

cp .env.example .env

6. Start the server

python main.py

Open http://localhost:8000 in your browser. ForgeRAG auto-generates a default forgerag.yaml config on first run with zero-config defaults:

• Database: SQLite (./storage/forgerag.db)
• Vector store: ChromaDB (./storage/chroma)
• Blob storage: Local filesystem (./storage/blobs)
• Embedder: text-embedding-3-small via OpenAI
• LLM: gpt-4o-mini via OpenAI

CLI Options

python main.py [OPTIONS]

Flag	Default	Description
--config PATH	auto-detect	Path to forgerag.yaml
--host HOST	0.0.0.0	Bind address (or $FORGERAG_HOST)
--port PORT	8000	Bind port (or $FORGERAG_PORT)
--reload	off	Hot-reload on code changes (development)
--workers N	4	Uvicorn worker processes (each runs its own ingestion queue; stuck jobs auto-recover on restart)
--log-level LEVEL	info	debug, info, warning, error
--init-only	off	Write default config and exit

Your First Document

1. Navigate to the Repository tab in the web UI
2. Drag and drop a PDF (or DOCX, PPTX, XLSX, HTML, Markdown) onto the page, or click the + icon to select files
3. The document is automatically queued for ingestion. Watch the toast notification for upload progress
4. Once status shows ready, switch to the Chat tab
5. Ask a question about the document. ForgeRAG returns an answer with highlighted source citations

What's Next

• Configuration Reference — customize backends, models, and retrieval parameters
• Architecture Overview — understand how ingestion, retrieval, and answering work
• Deployment Guide — run ForgeRAG with Docker or in production
• API Reference — integrate ForgeRAG into your own applications