michaelschiemer/deployment/stacks/redis/README.md

Redis Stack

External Redis Stack for the Custom PHP Framework application.

Overview

This Redis Stack provides:

• Cache Backend: Application-level caching (sessions, query results, objects)
• Queue Backend: Background job queue storage
• Session Storage: User session persistence
• Rate Limiting: Request rate limiting storage

Architecture Pattern: Following the same external stack pattern as PostgreSQL for consistency and separation of concerns.

Quick Start

# 1. Create environment configuration
cp .env.example .env

# 2. Set Redis password
echo "REDIS_PASSWORD=$(openssl rand -base64 32)" >> .env

# 3. Create app-internal network (if not exists)
docker network create app-internal

# 4. Start Redis Stack
docker compose up -d

# 5. Verify health
docker compose ps
docker compose exec redis-stack redis-cli ping
# Expected: PONG

Configuration

Environment Variables

REDIS_PASSWORD=your-secure-password   # Required for production
TZ=Europe/Berlin                      # Timezone for logs

Redis Configuration

Redis configuration is in redis.conf with production-optimized settings:

Persistence:

• RDB Snapshots: 15min/5min/1min intervals
• AOF (Append Only File): everysec fsync policy
• Combined persistence for data durability

Memory Management:

• Max Memory: 512MB (configurable)
• Eviction Policy: allkeys-lru (Least Recently Used)
• Lazy freeing for async deletion

Performance:

• TCP keepalive: 300s
• Active rehashing enabled
• Optimized client output buffers

Security

Password Protection:

# Set via Docker Secrets (recommended)
echo "your-redis-password" | docker secret create redis_password -

# Or via environment variable
REDIS_PASSWORD=your-password docker compose up -d

Network Isolation:

• Only accessible via app-internal Docker network
• Not exposed to public internet
• Protected mode enabled

Health Monitoring

# Check Redis health
docker compose exec redis-stack redis-cli ping

# Get Redis info
docker compose exec redis-stack redis-cli info

# Monitor real-time activity
docker compose exec redis-stack redis-cli monitor

# Check memory usage
docker compose exec redis-stack redis-cli info memory

# View slow queries
docker compose exec redis-stack redis-cli slowlog get 10

Integration with Application Stack

Production Setup

# In application root directory
docker compose \
  -f docker-compose.base.yml \
  -f docker-compose.production.yml \
  -f docker-compose.postgres-override.yml \
  -f docker-compose.redis-override.yml \
  up -d

Application Environment Variables

REDIS_HOST=redis-stack      # Container name from this stack
REDIS_PORT=6379
REDIS_PASSWORD=your-password  # Same as Redis Stack password

Maintenance

Backup

Redis persistence is handled automatically via:

• RDB: Snapshot backups in /data/dump.rdb
• AOF: Append-only log in /data/appendonly.aof

Manual Backup:

# Trigger immediate RDB snapshot
docker compose exec redis-stack redis-cli BGSAVE

# Copy backup files
docker cp redis-stack:/data/dump.rdb ./backups/redis-$(date +%Y%m%d).rdb

Restore

# Stop Redis
docker compose stop redis-stack

# Restore backup
docker cp ./backups/redis-backup.rdb redis-stack:/data/dump.rdb

# Start Redis
docker compose start redis-stack

Cleanup

# Clear specific database
docker compose exec redis-stack redis-cli -n 0 FLUSHDB

# Clear all databases (DANGEROUS!)
docker compose exec redis-stack redis-cli FLUSHALL

# Remove old AOF/RDB files
docker compose exec redis-stack sh -c "rm -f /data/*.aof.old /data/*.rdb.old"

Performance Tuning

Memory Optimization

# Check memory fragmentation
docker compose exec redis-stack redis-cli info memory | grep fragmentation

# Defragment if needed (Redis 4.0+)
docker compose exec redis-stack redis-cli MEMORY PURGE

Connection Limits

Adjust maxclients in redis.conf based on your application needs:

maxclients 10000  # Default, increase if needed

Persistence Trade-offs

For Cache-Only Usage:

# Disable persistence for maximum performance
save ""
appendonly no

For Critical Data:

# More frequent snapshots
save 300 1
save 60 10
appendfsync always  # Slower but safest

Troubleshooting

Connection Issues

# Test connection from application container
docker exec php sh -c 'redis-cli -h redis-stack -a $REDIS_PASSWORD ping'

# Check network connectivity
docker network inspect app-internal

Memory Issues

# Check current memory usage
docker compose exec redis-stack redis-cli info memory

# View evicted keys
docker compose exec redis-stack redis-cli info stats | grep evicted

# Increase memory limit (edit docker-compose.yml)
# deploy.resources.limits.memory: 1G

Performance Issues

# Check slow queries
docker compose exec redis-stack redis-cli slowlog get 10

# Monitor commands in real-time
docker compose exec redis-stack redis-cli monitor

# Analyze key patterns
docker compose exec redis-stack redis-cli --bigkeys

Architecture

Network Topology

┌─────────────────────────────────────────┐
│          app-internal Network           │
│                                         │
│  ┌──────────┐         ┌──────────────┐ │
│  │   PHP    │────────▶│ redis-stack  │ │
│  │   App    │         │   (Cache)    │ │
│  └──────────┘         └──────────────┘ │
│                                         │
│  ┌──────────┐                           │
│  │  Queue   │────────▶                  │
│  │  Worker  │         (Shared Redis)    │
│  └──────────┘                           │
│                                         │
└─────────────────────────────────────────┘

Data Separation

Database Indexes:

• DB 0: Application cache (default)
• DB 1: Session storage
• DB 2: Queue backend
• DB 3: Rate limiting
• DB 4-15: Available for other uses

Best Practices

1. Always use passwords in production
2. Monitor memory usage - set appropriate maxmemory limit
3. Enable persistence for critical data (sessions, queue)
4. Regular backups if using Redis as primary data store
5. Network isolation - never expose Redis port publicly
6. Health checks - monitor Redis availability
7. Resource limits - set Docker memory limits
8. Logging - check Redis logs for issues

Related Documentation

• Application Docker Compose
• Redis Override Configuration
• PostgreSQL Stack (similar pattern)
• Redis Official Documentation

Support

For issues or questions:

• Check Redis logs: docker compose logs redis-stack
• Test connectivity: docker compose exec redis-stack redis-cli ping
• Review configuration: docker compose exec redis-stack redis-cli config get '*'