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
```bash
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):**
```bash
curl -X GET http://localhost:8000/health \
  -H "X-Tenant-ID: acme-corp" \
  -H "X-KB-ID: kb-prod"
```

**Test Tenant 2 (techstart):**
```bash
curl -X GET http://localhost:8000/health \
  -H "X-Tenant-ID: techstart" \
  -H "X-KB-ID: kb-main"
```

### Verify Database Setup
```bash
# 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
```bash
# 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)
```bash
# 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**:
   ```bash
   make up
   make init-db
   # Test both tenants with curl commands above
   ```

2. **Integration Testing**:
   ```bash
   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