# Web3Proxy Redis Configuration

## Environment Variables

The Web3Proxy service now uses Redis for distributed idempotency storage across multiple instances.

### Required Environment Variables

- `REDIS_URL`: Redis connection string (default: `redis://localhost:6379`)
- `REDIS_PASSWORD`: Redis password (optional, for authenticated Redis instances)
- `LOG_LEVEL`: Logging level (default: `info`)

### Docker Configuration

When running in Docker, set the Redis URL to:
```
REDIS_URL=redis://redis:6379
```

For password-protected Redis instances:
```
REDIS_URL=redis://redis:6379
REDIS_PASSWORD=your_redis_password
```

### Production Configuration

For production deployments with password-protected Redis:

1. Set environment variables:
   ```bash
   export REDIS_URL=redis://your-redis-host:6379
   export REDIS_PASSWORD=your_secure_password
   ```

2. Or use a connection string with embedded password:
   ```
   REDIS_URL=redis://:your_password@your-redis-host:6379
   ```

### Fallback Behavior

If Redis is not available, the service will automatically fall back to in-memory storage with a warning message. This ensures the service continues to work even without Redis, but idempotency will only work within a single instance.

### Production Deployment

For production deployments with multiple Web3Proxy instances:

1. Ensure Redis is running and accessible
2. Set the `REDIS_URL` environment variable
3. Monitor Redis connection status in logs
4. Consider Redis clustering for high availability

### Idempotency Key Format

Idempotency keys are stored in Redis with the prefix `idempotency:` and have a TTL of 5 minutes.

Example Redis key: `idempotency:123e4567-e89b-12d3-a456-426614174000`

## Troubleshooting Redis Connection

If you see "Redis unavailable, using in-memory fallback" in health checks:

### Test Connectivity Locally

Run the diagnostic tool locally:
```bash
npm run test:redis
```

### Test Connectivity on Captain

1. SSH into your Captain server or use Captain's app console
2. Run the connectivity test script:
```bash
./scripts/test-redis-captain.sh
```

### Common Issues

1. **DNS Resolution Failed**
   - Check if the Redis hostname is correct
   - Verify DNS is configured properly
   - Try using IP address instead of hostname

2. **Connection Timeout**
   - Redis may not be running at the specified host
   - Firewall may be blocking port 6379
   - Check network connectivity between services

3. **Authentication Failed**
   - Verify `REDIS_PASSWORD` matches Redis configuration
   - For Redis URLs with embedded passwords, use format: `redis://:password@host:port`
   - Check Redis logs for authentication failures

4. **Redis Not Accepting Remote Connections**
   - Redis `bind` directive must include `0.0.0.0` or the specific interface IP
   - Edit `/etc/redis/redis.conf` and set: `bind 0.0.0.0 ::1`
   - Restart Redis after config changes

5. **Captain Service Discovery**
   - For Redis deployed on Captain, use internal service name
   - Format: `redis://srv-captain--redis:6379`
   - Ensure both services are on the same Docker network

### Health Check Status

- `healthy`: Redis is connected and working properly
- `degraded`: Redis unavailable, using in-memory fallback (service still works)
- `unhealthy`: Service cannot function properly

The service will automatically fall back to in-memory storage if Redis is unavailable. This is safe for single-instance deployments.
