docs/dev/intergrations/REDIS_CLOUD_SETUP_GUIDE.md

# Redis Cloud Setup Guide for SwiftOps

## Step-by-Step Setup (5 minutes)

### Step 1: Create Redis Cloud Account

1. **Go to Redis Cloud:**
   - Visit: https://redis.com/try-free/
   - Or: https://app.redislabs.com/#/sign-up

2. **Sign Up:**
   - Click "Get Started Free"
   - Use your email or sign in with Google/GitHub
   - No credit card required! ✅

3. **Verify Email:**
   - Check your email for verification link
   - Click to verify your account

---

### Step 2: Create Your First Database

1. **After login, you'll see the dashboard**
   - Click "Create database" or "New database"

2. **Select Plan:**
   - Choose **"Free"** plan
   - Shows: 30MB storage, 30 connections
   - Perfect for OTPs! ✅

3. **Configure Database:**
   ```
   Database Name: swiftops-otp
   Cloud Provider: AWS (or any)
   Region: Choose closest to your HuggingFace Space
           (US East is usually good)
   
   Port: 12345 (auto-assigned)
   Password: (auto-generated or set your own)
   ```

4. **Click "Activate database"**
   - Wait 30-60 seconds for provisioning

---

### Step 3: Get Your Connection Details

After database is created, you'll see the Configuration page.

**Click the "Connect" button** (next to "Connect using Redis CLI, Client, or Insight")

A popup will show your connection details:

```
Redis URL:
redis://default:YOUR_PASSWORD@redis-15438-c212.ap-south-1.ec2.cloud.redislabs.com:15438
```

**OR you'll see separate fields:**
```
Host: redis-15438-c212.ap-south-1.ec2.cloud.redislabs.com
Port: 15438
Password: abc123xyz456
Username: default
```

**If you see the full Redis URL - just copy it!** ✅

**If you see separate fields, build the URL:**
```
redis://default:PASSWORD@HOST:PORT
```

**Example from your screenshot:**
```
redis://default:YOUR_PASSWORD@redis-15438-c212.ap-south-1.ec2.cloud.redislabs.com:15438
```

**Copy this URL!** You'll need it for HuggingFace.

---

### Step 4: Add to HuggingFace Space

1. **Go to your HuggingFace Space:**
   - https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE

2. **Click "Settings" tab**

3. **Scroll to "Variables and secrets"**

4. **Click "New secret":**
   ```
   Name: REDIS_URL
   Value: redis://default:YOUR_PASSWORD@YOUR_ENDPOINT:YOUR_PORT
   ```

5. **Click "Save"**

6. **Restart your Space:**
   - Click "Factory reboot" or just push new code
   - Space will automatically use Redis Cloud

---

### Step 5: Verify It's Working

1. **Check Space logs:**
   ```
   ✅ OTP Service using Redis storage (redis://default:***@redis-12345...)
   ```

2. **Check health endpoint:**
   ```bash
   curl https://YOUR_SPACE.hf.space/health
   ```
   
   Should show:
   ```json
   {
     "components": {
       "redis": {
         "status": "connected",
         "storage_type": "redis"
       }
     }
   }
   ```

3. **Test OTP:**
   - Try sending an OTP via your app
   - Should work instantly!

---

## Quick Reference

### Your Redis Cloud Dashboard
- URL: https://app.redislabs.com/
- View: Database metrics, memory usage, connections

### Connection String Format
```
redis://[username]:[password]@[host]:[port]/[db]

Default username: default
DB number: 0 (default, can omit)
```

### Example URLs

**Basic:**
```
redis://default:mypassword@redis-12345.c1.us-east-1.ec2.cloud.redislabs.com:12345
```

**With SSL (if enabled):**
```
rediss://default:mypassword@redis-12345.c1.us-east-1.ec2.cloud.redislabs.com:12345
```

---

## Troubleshooting

### "Connection refused"
- ✅ Check password is correct
- ✅ Check endpoint and port
- ✅ Ensure database is "Active" in Redis Cloud dashboard

### "Authentication failed"
- ✅ Password must be URL-encoded if it contains special characters
- ✅ Username is usually "default"

### "Memory full"
- ✅ Check usage in Redis Cloud dashboard
- ✅ OTPs auto-expire (5-30 minutes)
- ✅ 30MB = ~60,000 OTPs (should never fill up)

### Test connection locally:
```bash
# Install redis-cli
brew install redis  # macOS
sudo apt install redis-tools  # Ubuntu

# Test connection
redis-cli -u "redis://default:PASSWORD@HOST:PORT" ping
# Should return: PONG
```

---

## Security Best Practices

1. **Never commit REDIS_URL to git**
   - Always use environment variables
   - Already in `.gitignore` as `.env`

2. **Use HuggingFace Secrets**
   - Secrets are encrypted
   - Not visible in logs
   - Only accessible to your Space

3. **Rotate password periodically**
   - Redis Cloud → Database → Configuration → Reset password
   - Update HuggingFace secret

4. **Monitor access**
   - Redis Cloud dashboard shows connections
   - Check for unusual activity

---

## Cost & Limits

### Free Tier (Forever Free)
- **Storage:** 30MB
- **Connections:** 30 concurrent
- **Bandwidth:** Unlimited
- **Uptime:** 99.99% SLA
- **Support:** Community

### When to Upgrade?
- If you exceed 30MB (unlikely for OTPs)
- If you need >30 concurrent connections
- If you want dedicated support

**For OTP service: Free tier is perfect!** ✅

---

## Alternative: Local Redis for Development

If you want to test locally without Redis Cloud:

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

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

**Docker:**
```bash
docker run -d -p 6379:6379 redis:alpine
export REDIS_URL=redis://localhost:6379/0
```

---

## Summary Checklist

- [ ] Created Redis Cloud account
- [ ] Created free database (30MB)
- [ ] Copied connection URL
- [ ] Added `REDIS_URL` secret to HuggingFace Space
- [ ] Restarted Space
- [ ] Verified Redis connection in logs
- [ ] Tested OTP functionality

**Done!** Your OTP service is now using Redis Cloud. 🎉

---

## Need Help?

- **Redis Cloud Docs:** https://docs.redis.com/latest/rc/
- **Redis Cloud Support:** https://redis.com/company/support/
- **HuggingFace Docs:** https://huggingface.co/docs/hub/spaces-overview

---

**Total Setup Time:** ~5 minutes  
**Cost:** $0 (free forever)  
**Maintenance:** None (fully managed)