LightRAG/starter/QUICK_START_MULTITENANT.md

LightRAG Multi-Tenant Docker - Quick Start Guide

🚀 Get Started in 3 Steps

Step 1: Setup Environment

cd starter
make setup           # Initialize .env from template

Step 2: Start Services with Multi-Tenant Demo Mode

make up             # Starts all services (PostgreSQL, Redis, API, WebUI)
make init-db        # Initialize database with 2 demo tenants

Step 3: Access the Services

Web UI:     http://localhost:3001
API Docs:   http://localhost:8000/docs
API Base:   http://localhost:8000

📊 Default Multi-Tenant Configuration

By default, the system starts with MULTITENANT_MODE=demo which provides:

Pre-configured Demo Tenants

Tenant	Knowledge Bases	Purpose
acme-corp	kb-prod, kb-dev	Enterprise tenant with production and dev KBs
techstart	kb-main, kb-backup	Startup tenant with main and backup KBs

Using the Multi-Tenant API

All API requests should include tenant headers:

# Example: Query as acme-corp
curl -X POST http://localhost:8000/api/v1/query \
  -H "X-Tenant-ID: acme-corp" \
  -H "X-KB-ID: kb-prod" \
  -H "Content-Type: application/json" \
  -d '{"query": "your query here"}'

# Example: Query as techstart
curl -X POST http://localhost:8000/api/v1/query \
  -H "X-Tenant-ID: techstart" \
  -H "X-KB-ID: kb-main" \
  -H "Content-Type: application/json" \
  -d '{"query": "your query here"}'

📋 Service Endpoints

Service	URL	Purpose
Web UI	http://localhost:3001	User interface
API Docs	http://localhost:8000/docs	Interactive API documentation
API Redoc	http://localhost:8000/redoc	Alternative API docs
API Health	http://localhost:8000/health	API health check
PostgreSQL	internal-only (container network)	Database (not exposed to host by default)
Redis	localhost:6379	Cache (internal use)

🎯 Useful Make Commands

# Service Management
make up              # Start all services
make down            # Stop all services
make restart         # Restart all services
make status          # Show service status
make logs            # Stream logs from all services
make logs-api        # Stream logs from API only

# Database Operations
make init-db         # Initialize database with multi-tenant schema
make db-shell        # Connect to PostgreSQL shell
make db-backup       # Create database backup
make db-restore      # Restore from backup
make db-reset        # Reset database (WARNING: deletes all data)

# Testing & Health
make api-health      # Check API health
make test            # Run tests for current mode
make test-all-scenarios  # Run all 3 testing scenarios

# Cleanup
make clean           # Remove stopped containers
make reset           # Full system reset (WARNING: deletes volumes)

🔐 Demo Database Credentials (local/dev only)

PostgreSQL User:     lightrag
PostgreSQL Password: lightrag_secure_password
PostgreSQL Database: lightrag_multitenant
PostgreSQL Host:     postgres (inside Docker container)
PostgreSQL Port:     5432 (internal-only; not forwarded to host)

Demo Login:
Username: admin
Password: password

🛠️ Testing Different Modes

Multi-Tenant Demo Mode (DEFAULT)

# Already set in .env as MULTITENANT_MODE=demo
make up
make init-db

# Test with both tenants
curl -H "X-Tenant-ID: acme-corp" -H "X-KB-ID: kb-prod" \
  http://localhost:8000/health

Single-Tenant Isolation Mode

# Switch to single tenant with multiple KBs
echo "MULTITENANT_MODE=on" >> .env
make restart
make init-db

Backward Compatibility Mode

# Switch to single-tenant compatibility (like main branch)
echo "MULTITENANT_MODE=off" >> .env
make restart
make init-db

# No tenant headers required
curl http://localhost:8000/health

📊 Database Tables Created

The initialization script (init-postgres.sql) creates:

Multi-Tenant Metadata:

• tenants - Tenant information
• knowledge_bases - KB metadata per tenant

Document Storage (tenant-isolated):

• documents - Document metadata
• document_chunks - Document segments
• document_status - Processing status
• embeddings_document - Document embeddings

Knowledge Graph (tenant-isolated):

• entities - Entity records
• relations - Relationship records
• embeddings_entity - Entity embeddings
• embeddings_relation - Relation embeddings

Caching & Storage (tenant-isolated):

• kv_storage - Key-value cache
• llm_cache - LLM response cache

All tables use composite keys: (tenant_id, kb_id, id)

🔍 Verify Multi-Tenant Isolation

From the Database

# Connect to database
make db-shell

# Check tenants
SELECT tenant_id, name FROM tenants;

# Check KBs
SELECT tenant_id, kb_id, name FROM knowledge_bases;

# Verify data isolation
SELECT COUNT(*) FROM documents WHERE tenant_id='acme-corp';
SELECT COUNT(*) FROM documents WHERE tenant_id='techstart';

# Exit
\q

From the API

# Health check
curl http://localhost:8000/health

# API docs (shows available endpoints)
curl http://localhost:8000/docs

🆘 Troubleshooting

Services Won't Start

# Check if ports are in use
lsof -i :3001  # WebUI
lsof -i :8000  # API
lsof -i :5432  # PostgreSQL (if published)

# View logs for errors
make logs

# Kill conflicting process and restart
kill -9 <PID>
make restart

Database Connection Issues

# Check PostgreSQL is healthy
make status

# View database logs
make logs-db

# Verify database exists
make db-shell
\l  # List databases
\q  # Exit

API Not Responding

# Check API health
make api-health

# Check API logs
make logs-api

# If needed, restart API
docker compose -p lightrag-multitenant restart lightrag-api

Reset Everything

# WARNING: This deletes all data!
make reset           # Full system reset (stops, removes containers and volumes)
make setup           # Re-initialize
make up              # Start fresh
make init-db         # Initialize with clean database

📚 Configuration Options

Edit .env to customize:

# Testing Mode (MUST be demo, on, or off)
MULTITENANT_MODE=demo    # demo ← DEFAULT for testing with 2 tenants

# Default Tenant/KB (when not provided in headers)
DEFAULT_TENANT=default
DEFAULT_KB=default

# LLM Configuration
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_BINDING_API_KEY=your_key_here

# Embedding Model
EMBEDDING_BINDING=ollama
EMBEDDING_MODEL=bge-m3:latest
EMBEDDING_BINDING_HOST=http://host.docker.internal:11434

# Database
POSTGRES_USER=lightrag
POSTGRES_PASSWORD=lightrag_secure_password
POSTGRES_DATABASE=lightrag_multitenant

# Server Ports
API_PORT=8000
WEBUI_PORT=3001

🎯 Key Features

✅ Multi-Tenant Isolation: Complete data separation between tenants
✅ Multiple KBs per Tenant: Each tenant can have multiple knowledge bases
✅ Composite Keys: Database-level isolation with (tenant_id, kb_id, id)
✅ Vector Search: pgvector with HNSW indexing
✅ Graph Database: Apache AGE for entity relationships
✅ Caching: Redis for LLM response caching
✅ Health Checks: Automatic service health monitoring

📖 More Information

For detailed testing strategies and advanced configuration, see:

• docs/adr/008-multi-tenant-testing-strategy.md - Complete testing guide
• QUICK_REFERENCE.md - Command reference guide
• README.md - Project overview

⚡ Performance Tips

For Better Search

• Use appropriate tenant and KB headers
• Database indexes are automatically created
• Vector search uses HNSW for fast similarity search

For Better Caching

• LLM responses are cached in Redis by default
• Set ENABLE_LLM_CACHE=true (default)

For Multi-Tenant Workloads

• Data is automatically isolated by tenant_id and kb_id
• No risk of cross-tenant data leakage

---

Last Updated: November 22, 2025
Status: ✅ Ready to Use - Multi-Tenant Demo Mode Enabled by Default
Platform: macOS/Linux/Windows (with Docker)