289 lines
5.7 KiB
Markdown
289 lines
5.7 KiB
Markdown
# Redis Setup Guide
|
|
|
|
Redis is used for distributed rate limiting and OTP tracking. It's **optional** - the service will use in-memory rate limiting if Redis is not available.
|
|
|
|
## Quick Start
|
|
|
|
### Option 1: Using Docker Compose (Recommended for Local Development)
|
|
|
|
Redis is already configured in `db/farmmarket-db/docker-compose.yml`. Start it with:
|
|
|
|
```bash
|
|
cd db/farmmarket-db
|
|
docker-compose up -d redis
|
|
```
|
|
|
|
Or start all services (PostgreSQL + Redis):
|
|
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
Then add to your `.env` file:
|
|
|
|
```env
|
|
REDIS_URL=redis://localhost:6379
|
|
```
|
|
|
|
### Option 2: Install Redis Locally
|
|
|
|
#### macOS (using Homebrew)
|
|
```bash
|
|
brew install redis
|
|
brew services start redis
|
|
```
|
|
|
|
#### Ubuntu/Debian
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install redis-server
|
|
sudo systemctl start redis-server
|
|
sudo systemctl enable redis-server
|
|
```
|
|
|
|
#### Windows
|
|
Download and install from: https://github.com/microsoftarchive/redis/releases
|
|
|
|
Then add to your `.env` file:
|
|
|
|
```env
|
|
REDIS_URL=redis://localhost:6379
|
|
```
|
|
|
|
### Option 3: Use Cloud Redis (Production)
|
|
|
|
For production, use a managed Redis service:
|
|
- **AWS ElastiCache**: `redis://your-elasticache-endpoint:6379`
|
|
- **Redis Cloud**: `redis://user:password@redis-cloud-host:6379`
|
|
- **Azure Cache for Redis**: `redis://your-cache.redis.cache.windows.net:6380?ssl=true`
|
|
|
|
Add to your `.env` file:
|
|
|
|
```env
|
|
REDIS_URL=redis://your-redis-host:6379
|
|
# OR with password
|
|
REDIS_URL=redis://:password@your-redis-host:6379
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
### Using REDIS_URL (Recommended)
|
|
|
|
Single connection string with all details:
|
|
|
|
```env
|
|
# Without password
|
|
REDIS_URL=redis://localhost:6379
|
|
|
|
# With password
|
|
REDIS_URL=redis://:password@localhost:6379
|
|
|
|
# With username and password
|
|
REDIS_URL=redis://username:password@localhost:6379
|
|
|
|
# With SSL (AWS ElastiCache, etc.)
|
|
REDIS_URL=rediss://your-redis-host:6379
|
|
```
|
|
|
|
### Using REDIS_HOST and REDIS_PORT
|
|
|
|
Separate host and port:
|
|
|
|
```env
|
|
REDIS_HOST=localhost
|
|
REDIS_PORT=6379
|
|
REDIS_PASSWORD=your_password # Optional
|
|
```
|
|
|
|
## Verification
|
|
|
|
### Test Redis Connection
|
|
|
|
Start your application and look for:
|
|
|
|
```
|
|
✅ Redis Client: Ready
|
|
```
|
|
|
|
If Redis is not available, you'll see:
|
|
|
|
```
|
|
⚠️ Redis not available. Rate limiting will use in-memory fallback.
|
|
```
|
|
|
|
### Test Redis Manually
|
|
|
|
```bash
|
|
# Using redis-cli (if installed)
|
|
redis-cli ping
|
|
# Should return: PONG
|
|
|
|
# Test connection with password
|
|
redis-cli -h localhost -p 6379 -a your_password ping
|
|
```
|
|
|
|
## Docker Compose Setup
|
|
|
|
The `docker-compose.yml` file includes Redis:
|
|
|
|
```yaml
|
|
services:
|
|
redis:
|
|
image: redis:7-alpine
|
|
container_name: farmmarket-redis
|
|
restart: always
|
|
ports:
|
|
- "6379:6379"
|
|
volumes:
|
|
- redis_data:/data
|
|
command: redis-server --appendonly yes
|
|
```
|
|
|
|
### Start Redis Only
|
|
|
|
```bash
|
|
cd db/farmmarket-db
|
|
docker-compose up -d redis
|
|
```
|
|
|
|
### Stop Redis
|
|
|
|
```bash
|
|
docker-compose stop redis
|
|
```
|
|
|
|
### View Redis Logs
|
|
|
|
```bash
|
|
docker-compose logs -f redis
|
|
```
|
|
|
|
## Production Recommendations
|
|
|
|
### 1. Use Managed Redis Service
|
|
|
|
For production, use a managed Redis service:
|
|
- **AWS ElastiCache** (recommended for AWS deployments)
|
|
- **Redis Cloud**
|
|
- **Azure Cache for Redis**
|
|
- **Google Cloud Memorystore**
|
|
|
|
### 2. Enable Redis Persistence
|
|
|
|
If using your own Redis instance:
|
|
- Enable AOF (Append-Only File) persistence
|
|
- Configure regular snapshots (RDB)
|
|
- Set up replication for high availability
|
|
|
|
### 3. Security
|
|
|
|
- Use password authentication in production
|
|
- Enable SSL/TLS for connections
|
|
- Restrict network access (firewall/VPC)
|
|
- Use IAM roles (for AWS ElastiCache)
|
|
|
|
### Example: AWS ElastiCache Configuration
|
|
|
|
```env
|
|
# AWS ElastiCache endpoint
|
|
REDIS_URL=redis://your-cluster.xxxxx.cache.amazonaws.com:6379
|
|
|
|
# With password
|
|
REDIS_URL=redis://:your-password@your-cluster.xxxxx.cache.amazonaws.com:6379
|
|
|
|
# With SSL (if enabled)
|
|
REDIS_URL=rediss://your-cluster.xxxxx.cache.amazonaws.com:6379
|
|
```
|
|
|
|
## Benefits of Using Redis
|
|
|
|
### Without Redis (In-Memory)
|
|
- ✅ Simple setup
|
|
- ✅ No external dependencies
|
|
- ❌ Rate limits reset on server restart
|
|
- ❌ Not shared across multiple server instances
|
|
- ❌ Limited scalability
|
|
|
|
### With Redis
|
|
- ✅ Persistent rate limits (survive restarts)
|
|
- ✅ Shared across multiple server instances
|
|
- ✅ Better scalability
|
|
- ✅ Can handle high traffic
|
|
- ❌ Requires Redis setup and maintenance
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Refused
|
|
|
|
**Error**: `ECONNREFUSED` or `Connection refused`
|
|
|
|
**Solutions**:
|
|
1. Check if Redis is running: `docker-compose ps` or `redis-cli ping`
|
|
2. Verify Redis port is correct (default: 6379)
|
|
3. Check firewall settings
|
|
4. Verify REDIS_URL or REDIS_HOST is correct
|
|
|
|
### Authentication Failed
|
|
|
|
**Error**: `NOAUTH Authentication required`
|
|
|
|
**Solutions**:
|
|
1. Add password to REDIS_URL: `redis://:password@host:6379`
|
|
2. Or set `REDIS_PASSWORD` environment variable
|
|
3. Verify password is correct
|
|
|
|
### Timeout Errors
|
|
|
|
**Error**: Connection timeout
|
|
|
|
**Solutions**:
|
|
1. Check network connectivity
|
|
2. Verify Redis host and port are correct
|
|
3. Check if Redis is behind a firewall
|
|
4. Increase connection timeout if needed
|
|
|
|
## Performance Tuning
|
|
|
|
### Connection Pooling
|
|
|
|
The Redis client automatically manages connections. Default settings are suitable for most use cases.
|
|
|
|
### Memory Optimization
|
|
|
|
If using local Redis:
|
|
|
|
```bash
|
|
# Set max memory (e.g., 256MB)
|
|
redis-cli CONFIG SET maxmemory 256mb
|
|
redis-cli CONFIG SET maxmemory-policy allkeys-lru
|
|
```
|
|
|
|
## Monitoring
|
|
|
|
### Check Redis Stats
|
|
|
|
```bash
|
|
redis-cli INFO stats
|
|
```
|
|
|
|
### Monitor Commands
|
|
|
|
```bash
|
|
redis-cli MONITOR
|
|
```
|
|
|
|
### Check Memory Usage
|
|
|
|
```bash
|
|
redis-cli INFO memory
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
1. Set up Redis using one of the options above
|
|
2. Add Redis configuration to your `.env` file
|
|
3. Restart your application
|
|
4. Verify connection with `✅ Redis Client: Ready` message
|
|
5. Test rate limiting to ensure it's working
|
|
|