LightRAG/starter/MULTITENANT_TESTING_ENABLED.md

Multi-Tenant Testing Enabled by Default

Summary

The LightRAG starter environment has been fully configured to test with multi-tenant mode enabled by default with 2 pre-configured demo tenants.

What Changed

1. ✅ Environment Configuration (.env)

• MULTITENANT_MODE=demo is now set by default
• This enables automatic multi-tenant testing with 2 demo tenants

2. ✅ Template Updated (env.example)

• Updated with clearer documentation
• Explicitly marked "demo" as the DEFAULT testing mode
• Includes information about the 2 pre-configured tenants:
  • Tenant 1: acme-corp (kb-prod, kb-dev)
  • Tenant 2: techstart (kb-main, kb-backup)

3. ✅ Docker Compose Configuration (docker-compose.yml)

• Added MULTITENANT_MODE environment variable to the lightrag-api service
• Defaults to demo mode when not explicitly set

4. ✅ Makefile Enhanced (Makefile)

make up command now displays:

📊 Testing Mode: demo
   ✓ Multi-Tenant Demo Mode (2 tenants)
     • Tenant 1: acme-corp (kb-prod, kb-dev)
     • Tenant 2: techstart (kb-main, kb-backup)

make init-db command now displays:

📦 Pre-configured Demo Tenants:
  ★ Tenant: acme-corp
    - kb-prod  (Production KB)
    - kb-dev   (Development KB)

  ★ Tenant: techstart
    - kb-main   (Main KB)
    - kb-backup (Backup KB)

💡 Tips:
  • Use X-Tenant-ID and X-KB-ID headers in API requests
  • Example: curl -H 'X-Tenant-ID: acme-corp' -H 'X-KB-ID: kb-prod' ...

5. ✅ Database Initialization (init-postgres.sql)

• Already includes SQL to create both demo tenants and their knowledge bases
• Creates composite key constraints: (tenant_id, kb_id, id)
• Prevents cross-tenant data access at database level

6. ✅ Documentation Created

• QUICK_START_MULTITENANT.md - Updated quick start guide with multi-tenant examples

How to Test

Quick Start

cd starter

# Step 1: Setup
make setup

# Step 2: Start services with demo mode
make up

# Step 3: Initialize database
make init-db

# Step 4: Access services
# Web UI:   http://localhost:3001
# API Docs: http://localhost:8000/docs

API Testing with Both Tenants

Test Tenant 1 (acme-corp):

curl -X GET http://localhost:8000/health \
  -H "X-Tenant-ID: acme-corp" \
  -H "X-KB-ID: kb-prod"

Test Tenant 2 (techstart):

curl -X GET http://localhost:8000/health \
  -H "X-Tenant-ID: techstart" \
  -H "X-KB-ID: kb-main"

Verify Database Setup

# Connect to database
make db-shell

# Check tenants
SELECT tenant_id, name FROM tenants;

# Check knowledge bases
SELECT tenant_id, kb_id, name FROM knowledge_bases;

# Exit
\q

Demo Tenant Details

Tenant 1: acme-corp

• ID: acme-corp
• Name: Acme Corporation
• Description: Enterprise customer - production deployment
• Knowledge Bases:
  • kb-prod - Production KB for live data
  • kb-dev - Development KB for testing

Tenant 2: techstart

• ID: techstart
• Name: TechStart Inc
• Description: Startup customer - evaluation environment
• Knowledge Bases:
  • kb-main - Main KB for primary knowledge
  • kb-backup - Backup KB for archival data

Key Features

✅ Multi-Tenant Isolation: Complete data separation at database level ✅ Composite Keys: (tenant_id, kb_id, id) prevents cross-tenant data access ✅ Automatic Setup: Demo tenants created automatically on make init-db ✅ Clear Output: make up displays the active testing mode ✅ API Headers: X-Tenant-ID and X-KB-ID for multi-tenant requests ✅ Database Verification: Built-in commands to verify tenant isolation

Switching Testing Modes

From Demo Mode → Single-Tenant Mode

# Edit .env
sed -i.bak 's/MULTITENANT_MODE=demo/MULTITENANT_MODE=on/' .env

# Restart services
make restart
make db-reset
make init-db

From Demo Mode → Compatibility Mode (Single-Tenant Like main branch)

# Edit .env
sed -i.bak 's/MULTITENANT_MODE=demo/MULTITENANT_MODE=off/' .env

# Restart services
make restart
make db-reset
make init-db

# Note: In this mode, X-Tenant-ID and X-KB-ID headers are not required
curl http://localhost:8000/health  # Works without headers

Files Modified

1. starter/.env - MULTITENANT_MODE=demo (already present)
2. starter/env.example - Updated documentation
3. starter/docker-compose.yml - Added MULTITENANT_MODE env var
4. starter/Makefile - Enhanced make up and make init-db output
5. starter/init-postgres.sql - Creates demo tenants (already present)

Files Created

1. starter/QUICK_START_MULTITENANT.md - Updated quick start guide

Verification Checklist

• ✅ make up displays "Multi-Tenant Demo Mode (2 tenants)"
• ✅ make init-db displays pre-configured demo tenants
• ✅ env.example clearly shows MULTITENANT_MODE=demo as default
• ✅ docker-compose.yml passes MULTITENANT_MODE to API service
• ✅ Database initialization creates acme-corp and techstart tenants
• ✅ Each tenant has its configured knowledge bases
• ✅ Composite key constraints prevent cross-tenant access
• ✅ API can be accessed with X-Tenant-ID and X-KB-ID headers

Next Steps

1. Manual Testing:

   make up
   make init-db
   # Test both tenants with curl commands above
   

2. Integration Testing:

   make test-multi
   make test-security
   

3. Documentation Review:

   • See docs/adr/008-multi-tenant-testing-strategy.md for detailed testing strategies
   • Review QUICK_START_MULTITENANT.md for additional examples

---

Status: ✅ Complete and Ready for Testing Date: November 22, 2025 Testing Mode: Multi-Tenant Demo (2 Tenants) - Enabled by Default