Job-List/QUICKSTART_REDIS.md

Quick Start: Redis/Valkey Caching

Prerequisites

1. Redis or Valkey server running and accessible
2. PocketBase instance running at https://pocketbase.ccllc.pro
3. Bun runtime installed

Setup Steps

1. Configure Environment

Add to your .env file (typically at /home/admin/secrets/.env):

# Redis/Valkey - use the same instance as Job-Info-Prod
REDIS_URL=redis://localhost:6379
# Or for production: REDIS_URL=redis://your-redis-server:6379

2. Install Dependencies

Already installed:

• ioredis (^5.8.2)
• @types/ioredis (^5.0.0)

3. Start the Server

cd /home/admin/Job-List
bun run dev

Server will start on port 3025 with Redis caching enabled.

Using the API

Frontend Integration

Update your frontend code to use the new cached endpoints:

Fetch All Jobs (Cached)

// OLD: Direct PocketBase fetch
const records = await pb.collection('Job_Info_TestEnv').getFullList({
  sort: 'Job_Number',
});

// NEW: Use cached endpoint
const response = await fetch('http://localhost:3025/api/jobs', {
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const { data, cached } = await response.json();
console.log(`Data ${cached ? 'from cache' : 'from PocketBase'}`);

Search Jobs (Cached)

// NEW: Search with caching
const searchQuery = 'Estimating';
const response = await fetch(`http://localhost:3025/api/jobs/search?q=${encodeURIComponent(searchQuery)}`, {
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const { data, cached, query } = await response.json();
console.log(`Found ${data.length} results for "${query}" ${cached ? '(cached)' : ''}`);

Clear Cache (Admin Only)

const response = await fetch('http://localhost:3025/api/cache/clear', {
  method: 'POST',
  headers: {
    'X-PocketBase-Token': pb.authStore.token
  }
});
const result = await response.json();
console.log(result.message); // "Cache cleared successfully"

Benefits

Performance Improvements

• First Request: ~200-500ms (from PocketBase)
• Cached Request: ~5-20ms (from Redis)
• Speed Improvement: 10-100x faster for cached requests

Load Reduction

• Reduces PocketBase queries by ~80-95%
• Allows multiple concurrent users without database strain
• Shared cache across multiple server instances

Monitoring

Check Server Logs

Look for these messages:

✓ Redis connected successfully
✓ Jobs fetched from cache
✓ Search results fetched from cache
✓ Cache cleared successfully

Monitor Redis

# Check Redis is running
redis-cli ping

# Monitor all Redis commands in real-time
redis-cli monitor

# Check cache keys
redis-cli keys "jobs:*"
redis-cli keys "search:*"

# Check specific key
redis-cli get "jobs:all:Job_Info_TestEnv"

# Check TTL (time to live) for a key
redis-cli ttl "jobs:all:Job_Info_TestEnv"

Cache Behavior

Cache TTL (Time To Live)

• Job Data: 5 minutes (300 seconds)
• Search Results: 3 minutes (180 seconds)

Cache Invalidation

Automatic invalidation occurs when:

• Data is submitted via /api/submit
• Manual cache clear via /api/cache/clear

Cache keys invalidated:

• jobs:* - All job data caches
• search:* - All search result caches

Troubleshooting

Problem: "Failed to connect to Redis"

Solution:

1. Check Redis is running: redis-cli ping
2. Verify REDIS_URL in environment
3. Check firewall/network connectivity
4. Try default: REDIS_URL=redis://localhost:6379

Problem: Cache always shows "cached: false"

Solution:

1. Check Redis connection is successful
2. Look for connection errors in server logs
3. Verify Redis has enough memory
4. Try clearing cache: redis-cli FLUSHALL

Problem: Seeing stale data

Solution:

1. Cache should auto-invalidate on updates
2. Manually clear: POST /api/cache/clear
3. Wait for TTL to expire (max 5 minutes)
4. Check update operations use /api/submit

Production Deployment

Connecting to Job-Info-Prod Redis

Update your production .env:

# Use the same Redis instance as Job-Info-Prod
REDIS_URL=redis://redis-prod-server:6379

# Or with authentication
REDIS_URL=redis://:your-password@redis-prod-server:6379

# Or with TLS
REDIS_URL=rediss://:your-password@redis-prod-server:6379

Security Considerations

1. Authentication: Use password-protected Redis in production
2. Network: Keep Redis on private network, not public internet
3. TLS: Use rediss:// (Redis with TLS) for encrypted connections
4. Firewall: Only allow connections from application servers

Scaling

Multiple application instances can share the same Redis:

┌─────────────┐
│  Instance 1 │───┐
└─────────────┘   │
                  ├───► Redis/Valkey
┌─────────────┐   │
│  Instance 2 │───┤
└─────────────┘   │
                  │
┌─────────────┐   │
│  Instance 3 │───┘
└─────────────┘

All instances benefit from shared cache.

Next Steps

1. ✅ Test caching with /api/jobs endpoint
2. ✅ Implement search in frontend using /api/jobs/search
3. ✅ Monitor cache hit rates and performance
4. 🔄 Plan migration to Job-Info-Prod for production
5. 🔄 Implement real-time cache updates via Redis PubSub

Support

For issues or questions:

1. Check server logs for error messages
2. Review REDIS_IMPLEMENTATION.md for detailed documentation
3. Test Redis connection with redis-cli
4. Verify environment variables are set correctly