LightRAG/starter/QUICK_REFERENCE.md

Quick Reference Guide - LightRAG Multi-Tenant Stack

🚀 First Time Setup (5 minutes)

# 1. Enter the starter directory
cd starter

# 2. Initialize environment
make setup

# 3. Edit .env with your API keys (if needed)
# nano .env

# 4. Start all services
make up

# 5. Initialize database (wait 30 seconds after 'make up')
make init-db

# 6. Verify everything is working
make api-health

# 7. Open in browser
# http://localhost:3000

---

📊 Monitoring & Debugging

# View all service logs in real-time
make logs

# View only API logs
make logs-api

# Check service status
make status

# Check API health
make api-health

# Connect to database
make db-shell

---

🗄️ Database Operations

# Create a backup
make db-backup
# Creates: ./backups/lightrag_backup_YYYYMMDD_HHMMSS.sql

# Restore from latest backup
make db-restore

# Connect to database shell
make db-shell
# Common commands:
# \dt                    - list all tables
# \di                    - list all indexes
# \d documents           - show documents table structure
# SELECT count(*) FROM documents;
# SELECT distinct tenant_id FROM documents;
# \q                     - quit

# WARNING: Delete and reinitialize database
make db-reset

---

🔄 Service Management

# Start services
make up

# Stop services
make down

# Restart services
make restart

# See what's running
make ps

# Stop and remove everything (keep data)
make down

# Complete reset (WARNING: deletes all data!)
make reset

---

🧪 Testing Multi-Tenant Features

# Test with curl - Insert document for tenant "acme-corp"
curl -X POST http://localhost:9621/api/v1/insert \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: acme-corp" \
  -H "X-KB-Id: kb-prod" \
  -d '{"document": "Sample document content"}'

# Test isolation - query as different tenant
curl "http://localhost:9621/api/v1/query" \
  -H "X-Tenant-Id: acme-corp" \
  -H "X-KB-Id: kb-prod" \
  -G --data-urlencode "param=test"

# Check isolation
curl "http://localhost:9621/api/v1/query" \
  -H "X-Tenant-Id: techstart" \
  -H "X-KB-Id: kb-main" \
  -G --data-urlencode "param=test"

# Run test suite
make test

# Run isolation tests
make test-isolation

---

🔧 Configuration Cheat Sheet

Change API Port

# In .env
API_PORT=9622

# Restart
make restart

Change WebUI Port

# In .env
WEBUI_PORT=3001

# Restart
make restart

Change Database Password

# In .env
POSTGRES_PASSWORD=your_new_password

# WARNING: Database must be reset if already initialized
make db-reset
make init-db

Use Different LLM (OpenAI)

# In .env
LLM_BINDING=openai
LLM_MODEL=gpt-4o
LLM_BINDING_API_KEY=sk-...

# Restart API
docker compose -p lightrag-multitenant restart lightrag-api

Use Different Embedding Model

# In .env
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_DIM=3072
EMBEDDING_BINDING_HOST=https://api.openai.com/v1
EMBEDDING_BINDING_API_KEY=sk-...

# Restart API
docker compose -p lightrag-multitenant restart lightrag-api

---

📱 Access Points

Service	URL	Purpose
WebUI	http://localhost:3000	Upload documents, visualize graph, query
API	http://localhost:9621	RESTful API access
API Health	http://localhost:9621/health	Check API status
PostgreSQL	localhost:5432	Database (use make db-shell)
Redis	localhost:6379	Cache (internal)

---

🐛 Troubleshooting Quick Fixes

"Port already in use"

# Find process using port 9621
lsof -i :9621

# Kill it
kill -9 <PID>

# Or change port in .env and restart

"Database is not ready"

# Wait longer and try again
sleep 30
make init-db

# Or check logs
make logs-db

"API not responding"

# Restart API
docker compose -p lightrag-multitenant restart lightrag-api

# Check logs
make logs-api

# Check health
make api-health

"Can't connect to database"

# Check database is running
make status

# Try connecting directly
make db-shell

# Reinitialize if needed
make db-reset
make init-db

"WebUI won't load"

# Check if it's running
make status

# View logs
make logs-webui

# Rebuild if needed
docker compose -p lightrag-multitenant down
docker compose -p lightrag-multitenant build --no-cache lightrag-webui
make up

---

📋 Sample Tenants & KBs

Default data created by make init-db:

Tenant: acme-corp
├── kb-prod     (Production knowledge base)
└── kb-dev      (Development knowledge base)

Tenant: techstart
├── kb-main     (Main knowledge base)
└── kb-backup   (Backup knowledge base)

---

🔐 Multi-Tenant Isolation

How to Create Document for Specific Tenant

import requests

headers = {
    "X-Tenant-Id": "acme-corp",
    "X-KB-Id": "kb-prod",
    "Content-Type": "application/json"
}

response = requests.post(
    "http://localhost:9621/api/v1/insert",
    headers=headers,
    json={"document": "Your document content"}
)

How to Verify Isolation

# Insert for tenant "acme-corp"
curl -X POST http://localhost:9621/api/v1/insert \
  -H "X-Tenant-Id: acme-corp" \
  -H "X-KB-Id: kb-prod" \
  -d '{"document": "acme-corp only"}'

# Query as "acme-corp" - should return data
curl "http://localhost:9621/api/v1/query" \
  -H "X-Tenant-Id: acme-corp" \
  -H "X-KB-Id: kb-prod" \
  -G --data-urlencode "param=acme"

# Query as "techstart" - should NOT return data
curl "http://localhost:9621/api/v1/query" \
  -H "X-Tenant-Id: techstart" \
  -H "X-KB-Id: kb-main" \
  -G --data-urlencode "param=acme"
  # Result: Empty or different data

---

💾 Backup & Restore Workflow

# Before making major changes
make db-backup
# Creates: ./backups/lightrag_backup_20251120_143022.sql

# Do your work...

# If something goes wrong
make db-restore

# Or manually restore specific backup
psql -U lightrag -d lightrag_multitenant < ./backups/lightrag_backup_20251120_143022.sql

---

🚨 Common Error Messages

Error	Cause	Solution
"Connection refused"	Services not running	make up
"Database does not exist"	Database not initialized	make init-db
"Port already in use"	Port conflict	Change port in .env
"Health check failed"	Service taking too long to start	Wait 30-60 seconds
"Permission denied"	Database permissions	make db-reset && make init-db
"Tenant not found"	Wrong tenant name	Check with make db-shell

---

📚 Full Help

make help

Shows all available commands with descriptions.

---

🔗 Useful Links

• LightRAG Docs: https://github.com/HKUDS/LightRAG
• Docker Docs: https://docs.docker.com/
• PostgreSQL Docs: https://www.postgresql.org/docs/
• pgvector Docs: https://github.com/pgvector/pgvector

---

✅ Health Check Verification

# API Health
curl http://localhost:9621/health

# Database Connection
make db-shell
# SELECT count(*) FROM tenants;
# \q

# Redis Connection
docker compose -p lightrag-multitenant exec redis redis-cli -a redis_secure_password ping

---

🎯 Next Steps

1. ✅ Setup Complete - Services are running
2. 📤 Upload Documents - Use WebUI at http://localhost:3000
3. 🔍 Create Queries - Ask questions about your documents
4. 📊 Visualize KB - View knowledge graph in WebUI
5. 🚀 Go to Production - Configure security, backups, monitoring

---

Version: 1.0
Last Updated: November 20, 2025
Status: Production Ready