LibreChat/redis-config
Atef Bellaaj 715bf1f9e9
🧪 feat: Changed-Line Mutation Selection and Single Quality Report Comment (#18111)
Select mutants from changed lines and ignore logging-only mutants; rank survivors by risk topic from whole-word identifier matches.
Publish one quality report comment, edited in place, with the verdict, change risk (coverage gaps and CRAP refactor hints) and mutation survivors grouped by line.
Bundle the report data into one quality-report artifact; shard artifacts are internal.
Map api/ source aliases into coverage evidence and enforce a per-shard execution budget.
Move Redis cluster runtime files out of the checkout.
2026-11-16 08:00:48 -05:00
..
certs
README.md 🚚 chore: Point Repository and Image References at LibreChat-AI (#16005) 2026-09-23 23:08:36 -04:00
redis-7001.conf
redis-7002.conf
redis-7003.conf
redis-tls.conf
start-cluster.sh 🧪 feat: Changed-Line Mutation Selection and Single Quality Report Comment (#18111) 2026-11-16 08:00:48 -05:00
start-redis-tls.sh
stop-cluster.sh

Redis Configuration and Setup

This directory contains comprehensive Redis configuration files and scripts for LibreChat development and testing, supporting both cluster and single-node setups with optional TLS encryption.

Supported Configurations

1. Redis Cluster (3 Nodes)

  • 3 Redis nodes running on ports 7001, 7002, and 7003
  • No replicas (each node is a master)
  • Automatic hash slot distribution across all nodes

2. Single Redis with TLS Encryption

  • Single Redis instance on port 6380 with TLS encryption
  • CA certificate validation for secure connections
  • Self-signed certificates with proper Subject Alternative Names

3. Standard Single Redis

  • Basic Redis instance on port 6379 (default)
  • No encryption - suitable for local development

All configurations are designed for local development and testing.

Prerequisites

  1. Redis must be installed on your system:

    # macOS
    brew install redis
    
    # Ubuntu/Debian
    sudo apt-get install redis-server
    
    # CentOS/RHEL
    sudo yum install redis
    
  2. Redis CLI should be available (usually included with Redis)

Quick Start

Option 1: Redis Cluster (3 Nodes)

# Navigate to the redis-config directory
cd redis-config

# Start and initialize the cluster
./start-cluster.sh

Option 2: Single Redis with TLS

# Start Redis with TLS encryption on port 6380
./start-redis-tls.sh

Option 3: Standard Redis

# Use system Redis on default port 6379
redis-server

Testing Your Setup

Test Cluster

# Connect to the cluster
redis-cli -c -p 7001

# Test basic operations
SET test_key "Hello World"
GET test_key

Test TLS Redis

# Test with CA certificate validation
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 ping

Test Standard Redis

# Connect to default Redis
redis-cli ping

Stopping Services

Stop Cluster

./stop-cluster.sh

Stop TLS Redis

# Find and stop TLS Redis process
ps aux | grep "redis-server.*6380"
kill <PID>

Configuration Files

  • redis-7001.conf - Configuration for node 1 (port 7001)
  • redis-7002.conf - Configuration for node 2 (port 7002)
  • redis-7003.conf - Configuration for node 3 (port 7003)

Scripts

  • start-cluster.sh - Starts and initializes the Redis cluster
  • stop-cluster.sh - Stops all Redis nodes and cleans up
  • start-redis-tls.sh - Starts Redis with TLS encryption and CA certificate validation
  • redis-tls.conf - TLS Redis configuration file

Directory Structure

redis-config/
├── README.md
├── redis-7001.conf         # Cluster node 1 configuration
├── redis-7002.conf         # Cluster node 2 configuration
├── redis-7003.conf         # Cluster node 3 configuration
├── redis-tls.conf          # TLS Redis configuration
├── start-cluster.sh        # Start cluster script
├── stop-cluster.sh         # Stop cluster script
├── start-redis-tls.sh      # Start TLS Redis script
├── certs/                  # TLS certificates (created automatically)
│   ├── ca-cert.pem         # Certificate Authority certificate
│   ├── ca-key.pem          # CA private key
│   ├── server-cert.pem     # Server certificate with SAN
│   ├── server-key.pem      # Server private key
│   ├── redis.dh            # Diffie-Hellman parameters
│   └── server.conf         # OpenSSL certificate configuration
├── data/                   # Data files (created automatically)
│   ├── 7001/               # Cluster node 1 data
│   ├── 7002/               # Cluster node 2 data
│   └── 7003/               # Cluster node 3 data
└── logs/                   # Log directory (created automatically)
    # Note: By default, Redis logs to stdout/stderr
    # Log files would be created here if enabled in config

Using with LibreChat

Update your .env file based on your chosen Redis configuration:

For Redis Cluster

USE_REDIS=true
REDIS_URI=redis://127.0.0.1:7001,redis://127.0.0.1:7002,redis://127.0.0.1:7003

For TLS Redis

USE_REDIS=true
REDIS_URI=rediss://127.0.0.1:6380
REDIS_CA=/path/to/LibreChat/redis-config/certs/ca-cert.pem

For Standard Redis

USE_REDIS=true
REDIS_URI=redis://127.0.0.1:6379

Optional Configuration

# Use environment variable for dynamic key prefixing
REDIS_KEY_PREFIX_VAR=K_REVISION

# Or set static prefix
REDIS_KEY_PREFIX=librechat

# Connection limits
REDIS_MAX_LISTENERS=40

# Ping interval to keep connection alive (seconds, 0 to disable)
REDIS_PING_INTERVAL=0

# Reconnection configuration
REDIS_RETRY_MAX_DELAY=3000      # Max delay between reconnection attempts (ms)
REDIS_RETRY_MAX_ATTEMPTS=10     # Max reconnection attempts (0 = infinite)
REDIS_CONNECT_TIMEOUT=10000     # Connection timeout (ms)
REDIS_ENABLE_OFFLINE_QUEUE=true # Queue commands when disconnected

TLS/SSL Redis Setup

For secure Redis connections using TLS encryption with CA certificate validation:

1. Start Redis with TLS

# Start Redis with TLS on port 6380
./start-redis-tls.sh

2. Configure LibreChat for TLS

Update your .env file:

# .env file - TLS Redis with CA certificate validation
USE_REDIS=true
REDIS_URI=rediss://127.0.0.1:6380
REDIS_CA=/path/to/LibreChat/redis-config/certs/ca-cert.pem

3. Test TLS Connection

# Test Redis TLS connection with CA certificate
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 ping

# Should return: PONG

# Test basic operations
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 set test_tls "TLS Working"
redis-cli --tls --cacert certs/ca-cert.pem -p 6380 get test_tls

4. Test Backend Integration

# Start LibreChat backend
npm run backend

# Look for these success indicators in logs:
# ✅ "No changes needed for 'USER' role permissions"
# ✅ "No changes needed for 'ADMIN' role permissions"
# ✅ "Server listening at http://localhost:3080"
# ✅ No "IoRedis connection error" messages

TLS Certificate Details

The TLS setup includes:

  • CA Certificate: Self-signed Certificate Authority for validation
  • Server Certificate: Contains Subject Alternative Names (SAN) for:
    • DNS: localhost
    • IP: 127.0.0.1
  • TLS Configuration:
    • TLS v1.2 and v1.3 support
    • No client certificate authentication required
    • Strong cipher suites (AES-256-GCM, ChaCha20-Poly1305)

Troubleshooting TLS

Certificate Validation Errors

# If you see "Hostname/IP does not match certificate's altnames"
# Check certificate SAN entries:
openssl x509 -in certs/server-cert.pem -text -noout | grep -A3 "Subject Alternative Name"

# Should show: DNS:localhost, IP Address:127.0.0.1

Connection Refused

# Check if Redis TLS is running
lsof -i :6380

# Check Redis TLS server logs
ps aux | grep redis-server

Backend Connection Issues

# Verify CA certificate path in .env
ls -la /path/to/LibreChat/redis-config/certs/ca-cert.pem

# Test LibreChat Redis configuration
cd /path/to/LibreChat
npm run backend
# Look for Redis connection errors in output

Common Operations

Check Cluster Status

# Cluster information
redis-cli -p 7001 cluster info

# Node information
redis-cli -p 7001 cluster nodes

# Check specific node
redis-cli -p 7002 info replication

Monitor Cluster

# Monitor all operations
redis-cli -p 7001 monitor

# Check memory usage
redis-cli -p 7001 info memory
redis-cli -p 7002 info memory
redis-cli -p 7003 info memory

Troubleshooting

Cluster Won't Start

  1. Check if Redis is installed: redis-server --version
  2. Check for port conflicts: netstat -tlnp | grep :700
  3. Check Redis processes: ps aux | grep redis-server
  4. Check if nodes are responding: redis-cli -p 7001 ping

Cluster Initialization Fails

  1. Ensure all nodes are running: ./start-cluster.sh
  2. Check cluster configuration: redis-cli -p 7001 cluster nodes
  3. Reset if needed: redis-cli -p 7001 CLUSTER RESET

Performance Issues

  1. Monitor memory usage: redis-cli -p 7001 info memory
  2. Check slow queries: redis-cli -p 7001 slowlog get 10
  3. Adjust maxmemory settings in configuration files

Configuration Details

Node Configuration

Each node is configured with:

  • Memory limit: 256MB with LRU eviction
  • Persistence: AOF + RDB snapshots
  • Clustering: Enabled with 15-second timeout
  • Logging: Notice level (logs to stdout/stderr by default)

Hash Slot Distribution

With 3 nodes and no replicas:

  • Node 1 (7001): Hash slots 0-5460
  • Node 2 (7002): Hash slots 5461-10922
  • Node 3 (7003): Hash slots 10923-16383

Security Note

Development Setup

The basic Redis cluster setup is designed for local development only.

TLS Setup

The TLS Redis configuration provides:

  • ✅ TLS encryption with CA certificate validation
  • ✅ Server certificate with proper Subject Alternative Names
  • ✅ Strong cipher suites (AES-256-GCM, ChaCha20-Poly1305)
  • ✅ Certificate validation via self-signed CA

Production Considerations

For production use, consider:

  • Authentication (requirepass or AUTH commands)
  • Client certificate authentication (tls-auth-clients yes)
  • Firewall configuration
  • Replica nodes for high availability
  • Proper certificate management (not self-signed)
  • Key rotation policies

Backup and Recovery

Backup

# Backup all nodes
mkdir -p backup
redis-cli -p 7001 BGSAVE
redis-cli -p 7002 BGSAVE
redis-cli -p 7003 BGSAVE

# Copy backup files
cp data/7001/dump.rdb backup/dump-7001.rdb
cp data/7002/dump.rdb backup/dump-7002.rdb
cp data/7003/dump.rdb backup/dump-7003.rdb

Recovery

# Stop cluster
./stop-cluster.sh

# Restore backup files
cp backup/dump-7001.rdb data/7001/dump.rdb
cp backup/dump-7002.rdb data/7002/dump.rdb
cp backup/dump-7003.rdb data/7003/dump.rdb

# Start cluster
./start-cluster.sh

Support

For Redis-specific issues:

For LibreChat integration: