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:

sudo apt update
sudo apt install redis-server
sudo systemctl start redis
export REDIS_URL=redis://localhost:6379/0

macOS:

brew install redis
brew services start redis
export REDIS_URL=redis://localhost:6379/0

Windows:

# 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:

export REDIS_URL=redis://localhost:6379/0

Or in .env:

REDIS_URL=redis://localhost:6379/0

Verify Redis is Working

1. Check health endpoint:

curl http://localhost:7860/health

Look for:

{
  "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:

echo $REDIS_URL

Test connection:

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! ✅