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:

   curl https://YOUR_SPACE.hf.space/health
   

   Should show:

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

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

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

Ubuntu:

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

Docker:

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)