LightRAG/starter/QUICK_START.md

# LightRAG Multi-Tenant Docker - Quick Start Guide

## 🚀 Get Started in 2 Minutes

### Step 1: Start Services
```bash
cd /Users/raphaelmansuy/Github/03-working/LightRAG/starter
docker compose -f docker-compose.yml -p lightrag-multitenant up -d
```

### Step 2: Wait for Services to Be Ready
```bash
# Check status (all should show "healthy" or "Up")
docker compose -f docker-compose.yml -p lightrag-multitenant ps

# Or wait a few seconds and visit:
# Web UI: http://localhost:3001
# API Docs: http://localhost:8000/docs
```

### Step 3: Stop Services
```bash
docker compose -f docker-compose.yml -p lightrag-multitenant down
```

## 📋 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 |
| PostgreSQL | internal-only (container network) | Database (not exposed to host by default) |
| Redis | localhost:6379 | Cache (internal use) |

## 🔐 Demo database credentials (local/dev only)

Use these defaults for local development or demos. Change `POSTGRES_PASSWORD` in `starter/.env` before running any shared/production systems.

```text
User:     lightrag
Password: lightrag_secure_password
Database: lightrag_multitenant
Host:     postgres (inside Docker)
Port:     5432 (internal-only; not forwarded to localhost by default)
```

## 📊 Database Tables

The following tables are automatically created:
- `lightrag_doc_full` - Full documents
- `lightrag_doc_chunks` - Document chunks
- `lightrag_vdb_chunks` - Vector embeddings for chunks
- `lightrag_vdb_entity` - Entity embeddings
- `lightrag_vdb_relation` - Relationship embeddings
- `lightrag_llm_cache` - LLM response cache
- `lightrag_doc_status` - Document processing status
- `lightrag_full_entities` - Complete entity records
- `lightrag_full_relations` - Complete relationship records

## 🛠️ Useful Commands

### View Logs
```bash
# All services
docker compose -f docker-compose.yml -p lightrag-multitenant logs -f

# Specific service
docker compose -f docker-compose.yml -p lightrag-multitenant logs -f lightrag-api
docker compose -f docker-compose.yml -p lightrag-multitenant logs -f lightrag-postgres
docker compose -f docker-compose.yml -p lightrag-multitenant logs -f lightrag-redis
```

### Database Operations
```bash
# Connect to PostgreSQL
docker compose -f docker-compose.yml -p lightrag-multitenant exec -T postgres \
  psql -U lightrag -d lightrag_multitenant

# List all databases
docker compose -f docker-compose.yml -p lightrag-multitenant exec -T postgres \
  psql -U lightrag -l

# Check extensions
docker compose -f docker-compose.yml -p lightrag-multitenant exec -T postgres \
  psql -U lightrag -d lightrag_multitenant -c "\dx"

# Test vector operations
docker compose -f docker-compose.yml -p lightrag-multitenant exec -T postgres \
  psql -U lightrag -d lightrag_multitenant -c \
  "SELECT '(1,2,3)'::vector <=> '(2,3,4)'::vector as cosine_distance;"
```

### Redis Operations
```bash
# Connect to Redis
docker compose -f docker-compose.yml -p lightrag-multitenant exec redis redis-cli

# Check Redis info
docker compose -f docker-compose.yml -p lightrag-multitenant exec -T redis redis-cli info
```

### Container Management
```bash
# Restart a service
docker compose -f docker-compose.yml -p lightrag-multitenant restart lightrag-api

# View service status
docker compose -f docker-compose.yml -p lightrag-multitenant ps

# Clean up everything (WARNING: deletes data!)
docker compose -f docker-compose.yml -p lightrag-multitenant down -v
```

## 📈 Extensions Installed

### pgvector (v0.8.1)
- **Purpose**: Vector embeddings and similarity search
- **Use Case**: Store and search document embeddings
- **Index Type**: HNSW (Hierarchical Navigable Small World)
- **Dimensions**: Supports up to 2000 dimensions

### Apache AGE (v1.5.0)
- **Purpose**: Graph database capabilities
- **Use Case**: Store and query entity relationships
- **Features**: Cypher query support
- **Status**: Ready for use (optional)

## 🔍 Troubleshooting

### Services Won't Start
```bash
# If you previously published ports to the host, check if they're in use. For the default
# compose setup PostgreSQL is internal-only and not bound to host interfaces.
lsof -i :6379  # Redis (if published)
lsof -i :9621  # API (if published)

# Kill processes if needed
kill -9 <PID>

# Then try starting again
docker compose up -d
```

### Database Connection Issues
```bash
# Check PostgreSQL is running
docker compose ps | grep postgres

# Check logs
docker compose logs lightrag-postgres

# Verify network connectivity
docker network inspect lightrag-multitenant_lightrag-network
```

### API Not Responding
```bash
# Check API logs
docker compose logs lightrag-api

# Verify API is listening
curl http://localhost:9621/docs

# Check database connection in logs
docker compose logs lightrag-api | grep "Connected"
```

### Reset Everything
```bash
# Stop all services
docker compose down

# Remove volumes (WARNING: deletes all data)
docker volume rm lightrag-multitenant_postgres_data lightrag-multitenant_redis_data

# Restart
docker compose up -d
```

## 📚 Documentation Files

1. **IMPLEMENTATION_SUMMARY.md** - Complete technical overview
2. **DOCKER_BUILD_COMPLETION_REPORT.md** - Detailed build report
3. **QUICK_REFERENCE.md** - Command reference
4. **README.md** - Original project README

## 🎯 Multi-Tenant Features

The system supports multiple independent tenants with:
- **Workspace Isolation**: Each workspace is completely isolated
- **Composite Keys**: (workspace_id, id) for all records
- **Cross-Tenant Prevention**: Database constraints prevent data leakage
- **Tenant-Aware Queries**: API automatically filters by workspace

### Create Multiple Workspaces
Each workspace has its own:
- Documents and chunks
- Vector embeddings
- Entity graph
- Cache entries
- Processing status tracking

## ⚙️ Configuration

### Environment Variables (in docker-compose.yml)
```yaml
POSTGRES_USER: lightrag
POSTGRES_PASSWORD: lightrag_secure_password
POSTGRES_DB: lightrag_multitenant
PGTZ: UTC
```

### PostgreSQL Performance Tuning
Current settings:
- `max_connections: 100`
- `shared_buffers: 256MB`
- `effective_cache_size: 1GB`
- `work_mem: 16MB`

Adjust in `docker-compose.yml` if needed for your workload.

## 🔗 API Integration Example

```bash
# Get API documentation
curl http://localhost:9621/docs

# Example API endpoint (check swagger for actual endpoints)
curl -X GET http://localhost:9621/api/endpoints
```

## 📱 Web UI Access

1. Open browser: http://localhost:9621
2. Configure your LLM provider (OpenAI, Azure, etc.)
3. Upload documents
4. Create knowledge base
5. Query the system

## 🔑 Key Points

✅ **Production Ready**: Fully tested and verified  
✅ **Multi-Tenant**: Complete workspace isolation  
✅ **Fast Search**: Vector and full-text search capability  
✅ **Graph Support**: Entity relationship management  
✅ **Persistent**: All data saved across restarts  
✅ **Monitored**: Health checks on all services  

## 🆘 Need Help?

1. Check the troubleshooting section above
2. Review logs: `docker compose logs lightrag-api`
3. Consult `DOCKER_BUILD_COMPLETION_REPORT.md` for detailed info
4. Check service status: `docker compose ps`

## ⚡ Performance Tips

### For Better Search Performance
```sql
-- Check vector index usage
SELECT * FROM pg_indexes WHERE tablename = 'lightrag_vdb_chunks';

-- Analyze query performance
EXPLAIN ANALYZE SELECT * FROM lightrag_vdb_chunks 
WHERE vector <#> '[0,1,0]'::vector LIMIT 10;
```

### For Better Caching
- Ensure Redis volume is mounted
- Monitor Redis memory: `redis-cli INFO memory`
- Set appropriate TTL for cache entries

### For Better Multi-Tenant Performance
- Use workspace_id in queries
- Leverage composite indexes
- Monitor slow queries: `log_min_duration_statement = 1000`

---

**Last Updated**: November 20, 2024  
**Status**: ✅ Ready to Use  
**Platform**: macOS/Linux/Windows (with Docker Desktop)