linkforty/infra/fly.io/fly.redis.md

Redis Setup on Fly.io

This guide covers setting up and managing Redis for LinkForty on Fly.io.

Overview

Redis is optional but highly recommended for LinkForty. According to the project documentation, Redis caching can reduce database queries by ~90% for repeated link lookups.

Fly.io partners with Upstash to provide managed Redis with:

• Serverless pricing (pay per request)
• Global replication
• TLS encryption
• Automatic scaling
• No idle charges

Creating a Redis Instance

Option 1: Upstash Redis via Fly.io (Recommended)

fly redis create --name linkforty-redis --region iad

You'll be prompted to choose a plan:

Free Tier:

• 256MB storage
• 10,000 commands/day
• Perfect for development
• Cost: $0/month

Eviction-$10:

• 1GB storage
• 100K commands/day
• Evicts least-recently-used keys when full
• Cost: $10/month

Eviction-$40:

• 5GB storage
• 500K commands/day
• Evicts least-recently-used keys when full
• Cost: $40/month

No-Eviction-$120:

• 5GB storage
• 1M commands/day
• Never evicts keys (blocks writes when full)
• Cost: $120/month

Option 2: Direct Upstash Setup

Alternatively, create directly at Upstash:

1. Sign up at https://upstash.com
2. Create a new Redis database
3. Choose region (match your Fly.io region)
4. Select pricing plan
5. Copy the connection string

Setting Redis URL

After creation, you'll receive a REDIS_URL. Set it as a secret:

fly secrets set REDIS_URL="rediss://default:password@host:6379" --app your-linkforty-app

Important: Use rediss:// (with double 's') for TLS encryption.

Redis URL Format

Your REDIS_URL should follow this format:

rediss://default:password@host:6379

Components:

• rediss:// - Redis with TLS (required for security)
• default - Username (Upstash default)
• password - Authentication token from Upstash
• host - Upstash endpoint (e.g., xxx-us-east-1.upstash.io)
• 6379 - Standard Redis port

Verifying Redis Connection

After setting the REDIS_URL, deploy and check logs:

fly deploy
fly logs

Look for:

Redis connected successfully

If Redis is unavailable, LinkForty will still work but will query the database for every link lookup (slower).

How LinkForty Uses Redis

Cache Strategy

LinkForty caches link lookups with this pattern:

1. Request: User visits https://your-app.fly.dev/abc123
2. Check Redis: Look for cached link data
   • Cache hit: Return immediately (< 5ms)
   • Cache miss: Query database, cache result
3. TTL: Cached for 1 hour (configurable)

What Gets Cached

• Link metadata (URLs, targeting rules, UTM params)
• Link expiration status
• User ID associations

What Doesn't Get Cached

• Click events (always written to database)
• Analytics aggregations
• Link creation/updates

Performance Benefits

With Redis enabled:

• Link redirects: ~5ms (vs ~50-200ms without cache)
• Database load: Reduced by ~90% for popular links
• Scalability: Handle 1000+ req/s on small instances

Without Redis:

• Every redirect hits the database
• Higher latency for users
• More database resources needed
• Lower maximum throughput

Monitoring Redis

Check Connection

# View app logs
fly logs --app your-linkforty-app | grep -i redis

# Check if REDIS_URL is set
fly secrets list --app your-linkforty-app

Monitor Usage (Upstash Dashboard)

Visit Upstash Console:

• View daily command count
• Monitor memory usage
• Check hit/miss ratio
• See latency metrics

Redis CLI Access

Connect to your Redis instance:

# Install redis-cli if needed
brew install redis  # macOS
apt-get install redis-tools  # Linux

# Connect using REDIS_URL
redis-cli -u "rediss://default:password@host:6379"

# Once connected:
PING                    # Should return PONG
KEYS link:*             # List cached links
GET link:abc123         # View specific cached link
TTL link:abc123         # Check time-to-live
INFO stats              # View Redis stats
DBSIZE                  # Count of keys
FLUSHDB                 # ⚠️ Clear all cache (use with caution)

Cache Invalidation

Automatic Invalidation

LinkForty automatically invalidates cache when:

• Link is updated
• Link is deleted
• Link expires

Manual Invalidation

If needed, clear cache for a specific link:

redis-cli -u "rediss://default:password@host:6379" DEL link:abc123

Clear all cached links:

redis-cli -u "rediss://default:password@host:6379" FLUSHDB

Cache TTL Configuration

Default TTL is 1 hour. To adjust, modify the caching layer in LinkForty:

// In your Redis cache implementation
const TTL = 60 * 60; // 1 hour in seconds
await redis.set(key, value, 'EX', TTL);

Consider:

• Short TTL (5-15 min): More accurate, higher DB load
• Long TTL (1-4 hours): Lower DB load, potentially stale data
• No TTL: Manual invalidation only (not recommended)

Scaling Redis

When to Upgrade

Monitor these metrics:

• Commands/day approaching limit → Upgrade plan
• Memory usage > 80% → Upgrade plan or enable eviction
• High latency (>10ms) → Consider global replication
• Frequent cache misses → Increase TTL or memory

Upgrade Plan

# Via Upstash dashboard
# https://console.upstash.com/ → Select database → Change plan

No downtime during plan changes.

Global Replication (Multi-Region)

For lower latency worldwide, enable global replication:

1. In Upstash dashboard, enable "Read Replicas"
2. Choose replica regions (e.g., us-east, eu-west, ap-southeast)
3. Upstash automatically routes reads to nearest replica

Cost: ~2x base price per replica region

Security

TLS Encryption

Always use rediss:// (TLS) in production:

# ✅ Correct (encrypted)
rediss://default:password@host:6379

# ❌ Wrong (unencrypted)
redis://default:password@host:6379

Password Rotation

Rotate Redis password quarterly:

1. In Upstash dashboard: Database → Settings → Reset Password
2. Copy new password
3. Update secret:

   fly secrets set REDIS_URL="rediss://default:NEW_PASSWORD@host:6379"
   

4. Deploy:

   fly deploy
   

Network Security

Upstash Redis is publicly accessible but:

• Requires authentication (password)
• Uses TLS encryption
• Supports IP allowlisting (in Upstash dashboard)

For extra security, enable IP allowlisting:

1. Get your Fly.io app's public IPs: fly ips list
2. In Upstash dashboard: Settings → IP Allowlist
3. Add Fly.io IPs

Troubleshooting

Redis Connection Fails

# Check REDIS_URL is set correctly
fly secrets list --app your-linkforty-app

# Test connection manually
redis-cli -u "rediss://default:password@host:6379" PING

# Check app logs for errors
fly logs --app your-linkforty-app | grep -i redis

Common issues:

• Wrong password → Reset in Upstash dashboard
• Missing rediss:// protocol → Use TLS version
• Firewall blocking port 6379 → Check Upstash IP allowlist

High Latency

# Test latency
redis-cli -u "rediss://default:password@host:6379" --latency

# Check from your app
redis-cli -u "rediss://default:password@host:6379" SLOWLOG GET 10

Solutions:

• Enable global replication for multi-region apps
• Check Upstash status page
• Verify region matches your app region

Memory Full (Eviction Errors)

# Check memory usage
redis-cli -u "rediss://default:password@host:6379" INFO memory

# Check eviction stats
redis-cli -u "rediss://default:password@host:6379" INFO stats | grep evicted

Solutions:

• Upgrade to larger plan
• Reduce cache TTL
• Implement selective caching (only cache popular links)

Cache Hit Rate Too Low

# Check hit rate
redis-cli -u "rediss://default:password@host:6379" INFO stats
# Look for: keyspace_hits and keyspace_misses

Low hit rate causes:

• TTL too short
• Traffic pattern (mostly unique links)
• Not enough memory (evictions)

Solutions:

• Increase TTL (if data staleness is acceptable)
• Increase memory (upgrade plan)
• Profile which links are being accessed

Running Without Redis

LinkForty works without Redis, but with performance trade-offs:

Performance Without Redis

• Latency: ~50-200ms per redirect (vs ~5ms with Redis)
• Database load: 10x higher
• Throughput: Lower maximum requests/second
• Costs: Higher database instance needed

Disabling Redis

Simply don't set REDIS_URL:

fly secrets unset REDIS_URL --app your-linkforty-app

LinkForty detects missing Redis and falls back to database-only mode.

When to Skip Redis

Skip Redis if:

• Very low traffic (< 100 redirects/day)
• Budget is extremely tight
• All links are unique (no repeated lookups)
• Development/testing only

Cost Optimization

Free Tier (Good for Development)

• 256MB storage
• 10,000 commands/day
• ~300 redirects/day with caching
• Cost: $0/month

Small Production ($10/month)

• 1GB storage
• 100K commands/day
• ~3,000 redirects/day with caching
• Cost: $10/month

Estimate Your Needs

Calculate commands/day:

• Link redirect with cache hit: 1 command (GET)
• Link redirect with cache miss: 2 commands (GET + SET)
• Assume 50% hit rate: 1.5 commands per redirect
• For 10,000 redirects/day: ~15,000 commands/day

Choose plan accordingly.

Cost Monitoring

# In Upstash dashboard
# View: Billing → Current Usage

Set up alerts for:

• 80% of command limit reached
• 80% of storage used

Alternative: Self-Hosted Redis

Instead of Upstash, you can run Redis on Fly.io:

Create Redis Machine

fly launch --image redis:7-alpine --name linkforty-redis --region iad

Pros:

• Lower cost for high traffic
• Full control

Cons:

• You manage backups
• You manage security
• No automatic scaling
• More operational overhead

Not recommended unless you have specific requirements or very high traffic (>1M commands/day).

Best Practices

1. Always use TLS (rediss://)
2. Set reasonable TTL (1-4 hours for links)
3. Monitor hit rate (target >70%)
4. Rotate passwords quarterly
5. Enable global replication for multi-region deployments
6. Set up alerts for command limits
7. Start small (free tier) and scale up based on metrics

Resources

• Upstash Documentation
• Redis Documentation
• Fly.io Redis Guide
• Cache Invalidation Strategies

---

Need Help?

• Upstash Support: https://upstash.com/docs/redis/support
• Redis Community: https://redis.io/community
• Fly.io Community: https://community.fly.io/