API Cache Deployment Strategy¶

Overview¶

This document outlines the deployment strategy for the Redis-based API caching implementation in the Bean.business backend.

Cache Configuration¶

The system uses Redis with Symfony's tag-aware cache adapter for optimal performance and cache invalidation. The following pools are configured:

api.cache: Main cache pool (1 hour TTL) for general API responses - Redis database 1
api.cache.short: Short-term cache (5 minutes TTL) for frequently changing data - Redis database 2
api.cache.long: Long-term cache (24 hours TTL) for rarely changing reference data - Redis database 3

Environment Configuration¶

Development/Docker¶

REDIS_URL=redis://redis:6379

Production¶

# Local Redis
REDIS_URL=redis://localhost:6379

# Redis with authentication
REDIS_URL=redis://:password@redis-server:6379

# Managed Redis service
REDIS_URL=redis://username:password@your-redis-host:6379

Deployment Strategy¶

Recommended Approach: Clear Redis Cache on Deployment¶

Clear Redis cache with each deployment to ensure data consistency and prevent issues.

Benefits:¶

✅ No stale data after code changes
✅ No cache structure compatibility issues
✅ Simple deployment process
✅ Cache rebuilds quickly for critical endpoints
✅ Redis provides immediate cache invalidation across all app instances

Implementation:¶

# Clear all API cache pools
php bin/console cache:pool:clear api.cache api.cache.short api.cache.long

# Alternative: Clear specific pools individually
php bin/console cache:pool:clear api.cache
php bin/console cache:pool:clear api.cache.short  
php bin/console cache:pool:clear api.cache.long

# Or clear all cache (includes Symfony app cache)
php bin/console cache:clear --env=prod

Docker/Container Deployment:¶

# In your Dockerfile or deployment script
RUN php bin/console cache:pool:clear api.cache api.cache.short api.cache.long

# Or include in entrypoint script
COPY docker-entrypoint.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/docker-entrypoint.shHo
ENTRYPOINT ["docker-entrypoint.sh"]

Redis Deployment Options¶

Option 1: External Redis Service (Recommended for Production)¶

Use managed Redis service (AWS ElastiCache, Redis Cloud, etc.)
High availability and automatic failover
Professional monitoring and maintenance
Set REDIS_URL to point to external service

Option 2: Redis Container (Development/Small Production)¶

# docker-compose.yml
services:
  app:
    environment:
      REDIS_URL: redis://redis:6379
  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
volumes:
  redis_data:

Option 3: Local Redis Installation¶

Install Redis directly on server
Configure authentication and persistence
Set REDIS_URL=redis://:password@localhost:6379

Cache Warming (Optional)¶

To improve first-request performance after deployment, warm critical endpoints:

The cache warmup script is located at deploy/scripts/cache-warmup.sh and uses Docker to warm up endpoints from within the container.

Usage:

# Warm cache for a specific Docker Compose project
./deploy/scripts/cache-warmup.sh your-project-name

# Example for main backend
./deploy/scripts/cache-warmup.sh backend

# Example for worktree 
./deploy/scripts/cache-warmup.sh backend-worktree-name

The script automatically:

Finds the PHP container for the specified project
Warms up critical endpoints from within the container
Handles errors gracefully for endpoints with no data

Deployment Checklist¶

[ ] Redis server running and accessible
[ ] REDIS_URL environment variable configured
[ ] Clear Redis cache on deployment: php bin/console cache:pool:clear api.cache api.cache.short api.cache.long
[ ] Test Redis connection: php bin/console debug:container --env-vars | grep REDIS
[ ] (Optional) Run cache warmup: ./scripts/cache-warmup.sh https://your-domain.com
[ ] Monitor first-request performance after cache clear
[ ] Check logs for Redis connection or cache-related errors

Cache Monitoring¶

Log Monitoring¶

Cache operations are logged. Monitor for:

Cache invalidation events
Cache clear operations
Any cache-related errors

Performance Monitoring¶

Track these metrics:

API response times (should improve after first request)
Database query counts (should decrease for cached endpoints)
Cache hit/miss rates (if monitoring tools support it)

Redis Database Usage by Environment¶

Development: Uses Redis databases 1, 2, 3 on redis:6379 (Docker service)
Production: Uses Redis databases 1, 2, 3 on configured REDIS_URL
Test: Uses Redis databases 1, 2, 3 on test environment Redis instance

Database Allocation:¶

Database 1: api.cache (1 hour TTL)
Database 2: api.cache.short (5 minutes TTL)
Database 3: api.cache.long (24 hours TTL)

Troubleshooting¶

Redis Connection Issues¶

Test Redis connectivity: redis-cli -h your-redis-host ping
Verify REDIS_URL format: Should be redis://[username:password@]host:port
Check network access: Ensure app server can reach Redis server
Verify Redis is running: systemctl status redis or check container logs

Cache Not Working¶

Check Redis connection in Symfony: php bin/console debug:container --env-vars | grep REDIS
Verify cache pool configuration in config/packages/cache.php
Test cache manually: php bin/console cache:pool:clear api.cache && [make request]
Check if cache service is properly injected in repositories

Performance Issues¶

Monitor Redis memory usage: redis-cli info memory
Check for excessive cache invalidation in logs
Monitor Redis slow queries: redis-cli slowlog get 10
Consider adjusting TTL values for different use cases
Use Redis monitoring tools (RedisInsight, etc.)

Cache Corruption or Connection Errors¶

Clear all cache: php bin/console cache:pool:clear api.cache api.cache.short api.cache.long
Restart Redis server: systemctl restart redis or restart container
Verify Redis configuration: Check authentication, memory limits, persistence
Check Redis logs for errors: /var/log/redis/redis-server.log

Manual Cache Management¶

Clear All API Cache¶

php bin/console cache:pool:clear api.cache api.cache.short api.cache.long

Clear Specific Cache Tags¶

// In code or command
$cacheManager = $container->get(ApiCacheManager::class);
$cacheManager->invalidateVarieties();
$cacheManager->invalidateRegions();
$cacheManager->invalidateCountries();
$cacheManager->invalidateCoffeeBeans();

View Cache Stats¶

The ApiCacheManager::getStats() method provides basic cache information.

Security Considerations¶

Cache files contain serialized data - ensure proper file permissions
Cache directory should not be web-accessible
Consider cache content when handling sensitive data
Regular cleanup of old cache files (handled automatically by Symfony)