docs/dev/intergrations/REDIS_SETUP.md

# Redis Setup for OTP Service

## Overview
The OTP service uses Redis for temporary storage of verification codes. Redis provides:
- Fast in-memory storage
- Automatic expiry (TTL)
- Production-ready scalability
- No cleanup jobs needed

## HuggingFace Spaces - Use Redis Cloud

HuggingFace Spaces doesn't allow running Redis server in containers. Use **Redis Cloud** (free tier):

### Setup Redis Cloud (Free 30MB)

1. **Sign up:** https://redis.com/try-free/
2. **Create database:**
   - Select "Free" plan (30MB - enough for ~30,000 OTPs)
   - Choose region closest to your HF Space
   - Copy the connection URL

3. **Add to HF Space:**
   - Go to your Space Settings → Variables
   - Add secret: `REDIS_URL`
   - Value: `redis://default:YOUR_PASSWORD@YOUR_HOST:PORT`

Example:
```
REDIS_URL=redis://default:abc123xyz@redis-12345.c1.us-east-1.ec2.cloud.redislabs.com:12345
```

That's it! ✅ The app will automatically connect to Redis Cloud.

## Local Development

### Option 1: Use Redis Cloud (Recommended)
Same as production - use Redis Cloud free tier.

### Option 2: Install Redis Locally

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install redis-server
sudo systemctl start redis
export REDIS_URL=redis://localhost:6379/0
```

**macOS:**
```bash
brew install redis
brew services start redis
export REDIS_URL=redis://localhost:6379/0
```

**Windows:**
```bash
# Use WSL2 or Docker
wsl --install
# Then follow Ubuntu instructions
```

### Option 3: No Redis (Development Only)
The app automatically falls back to in-memory storage if Redis is unavailable.

**Warning:** In-memory storage:
- ❌ Lost on restart
- ❌ Doesn't work with multiple servers
- ✅ Fine for local testing

## Configuration

Set Redis URL via environment variable:
```bash
export REDIS_URL=redis://localhost:6379/0
```

Or in `.env`:
```
REDIS_URL=redis://localhost:6379/0
```

## Verify Redis is Working

1. **Check health endpoint:**
```bash
curl http://localhost:7860/health
```

Look for:
```json
{
  "components": {
    "redis": {
      "status": "connected",
      "storage_type": "redis"
    }
  }
}
```

2. **Check logs:**
```
✅ OTP Service using Redis storage (redis://localhost:6379/0)
```

If you see:
```
⚠️ Redis connection failed
⚠️ Falling back to in-memory storage
```
Then Redis is not running or not accessible.

## Redis Cloud Configuration

Redis Cloud free tier provides:
- **Max Memory:** 30MB (enough for ~30,000 OTPs)
- **Eviction Policy:** allkeys-lru (removes oldest keys when full)
- **SSL/TLS:** Encrypted connections
- **High Availability:** 99.99% uptime SLA

## Troubleshooting

### Connection refused
Check your `REDIS_URL` environment variable:
```bash
echo $REDIS_URL
```

Test connection:
```bash
redis-cli -u $REDIS_URL ping
# Should return: PONG
```

### Authentication failed
Ensure your Redis Cloud password is correct in the URL:
```
redis://default:YOUR_PASSWORD@host:port
```

### Memory full
Free tier has 30MB. If full:
- OTPs auto-expire (5-30 minutes)
- Oldest keys are evicted automatically (LRU policy)
- Upgrade to paid tier if needed

## Why 30MB is Enough

**OTP Storage:**
- Each OTP: ~500 bytes (code, metadata, timestamps)
- 30MB = ~60,000 OTPs
- OTPs expire in 5-30 minutes
- Even with 1000 users/hour, you'll use <1MB

**Redis Cloud Free Tier is perfect for OTPs!** ✅

## Production Scaling

If you outgrow 30MB:
1. **Redis Cloud Pro:** $5/month for 250MB
2. **AWS ElastiCache:** Pay-as-you-go
3. **Self-hosted:** On your own infrastructure

For most apps, free tier is sufficient! ✅