Redis Setup - Sockudo

Redis is essential for scaling Sockudo across multiple nodes. This guide covers Redis standalone, Redis Cluster, and Redis Sentinel configurations.

Why Use Redis with Sockudo?

Horizontal Scaling: Share WebSocket connections across multiple Sockudo nodes
High Availability: Redis Sentinel provides automatic failover
Performance: Redis Cluster distributes load across multiple masters
Persistence: Optional data persistence for app configuration
Multiple Backends: Supports adapter, cache, queue, and rate limiter

Redis Standalone

Best for single-region deployments with 1-3 Sockudo nodes.

Install Redis

# Ubuntu/Debian
sudo apt update
sudo apt install redis-server

# CentOS/RHEL
sudo yum install redis

# macOS
brew install redis

# Docker
docker run -d --name redis -p 6379:6379 redis:7-alpine

Configure Redis

Edit /etc/redis/redis.conf:

# Bind to all interfaces (or specific IP)
bind 0.0.0.0

# Set password for security
requirepass your-strong-password

# Enable persistence
save 900 1
save 300 10
save 60 10000

# Increase max connections
maxclients 10000

# Memory settings
maxmemory 2gb
maxmemory-policy allkeys-lru

Restart Redis:

sudo systemctl restart redis

Configure Sockudo

Set environment variables:

ADAPTER_DRIVER=redis
CACHE_DRIVER=redis
QUEUE_DRIVER=redis
RATE_LIMITER_DRIVER=redis

DATABASE_REDIS_HOST=localhost
DATABASE_REDIS_PORT=6379
DATABASE_REDIS_PASSWORD=your-strong-password
DATABASE_REDIS_DB=0

Or use config/config.json:

{
  "adapter": {
    "driver": "redis"
  },
  "cache": {
    "driver": "redis"
  },
  "queue": {
    "driver": "redis"
  },
  "rate_limiter": {
    "driver": "redis"
  },
  "database": {
    "redis": {
      "host": "localhost",
      "port": 6379,
      "password": "your-strong-password",
      "db": 0,
      "key_prefix": "sockudo:"
    }
  }
}

Verify Connection

# Test Redis connection
redis-cli -h localhost -p 6379 -a your-strong-password ping
# Should return: PONG

# Start Sockudo
./target/release/sockudo

# Check logs for Redis connection
# Should see: "Connected to Redis adapter"

Redis Sentinel (High Availability)

Redis Sentinel provides automatic failover and high availability.

Architecture

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  Sentinel 1 │    │  Sentinel 2 │    │  Sentinel 3 │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
       ┌──────▼──────┐       ┌───────▼──────┐
       │Redis Master │◄──────│ Redis Replica│
       └─────────────┘       └──────────────┘

Deploy Redis with Sentinel

Using Docker Compose

Create docker-compose.redis-sentinel.yml:

version: '3.8'

services:
  redis-master:
    image: redis:7-alpine
    command: redis-server --requirepass redispass --masterauth redispass
    ports:
      - "6379:6379"

  redis-replica:
    image: redis:7-alpine
    command: redis-server --replicaof redis-master 6379 --requirepass redispass --masterauth redispass
    depends_on:
      - redis-master

  sentinel1:
    image: redis:7-alpine
    command: >
      sh -c 'echo "port 26379
      sentinel monitor mymaster redis-master 6379 2
      sentinel auth-pass mymaster redispass
      sentinel down-after-milliseconds mymaster 5000
      sentinel parallel-syncs mymaster 1
      sentinel failover-timeout mymaster 10000" > /etc/sentinel.conf &&
      redis-sentinel /etc/sentinel.conf'
    ports:
      - "26379:26379"
    depends_on:
      - redis-master
      - redis-replica

  sentinel2:
    image: redis:7-alpine
    command: >
      sh -c 'echo "port 26379
      sentinel monitor mymaster redis-master 6379 2
      sentinel auth-pass mymaster redispass
      sentinel down-after-milliseconds mymaster 5000
      sentinel parallel-syncs mymaster 1
      sentinel failover-timeout mymaster 10000" > /etc/sentinel.conf &&
      redis-sentinel /etc/sentinel.conf'
    depends_on:
      - redis-master
      - redis-replica

  sentinel3:
    image: redis:7-alpine
    command: >
      sh -c 'echo "port 26379
      sentinel monitor mymaster redis-master 6379 2
      sentinel auth-pass mymaster redispass
      sentinel down-after-milliseconds mymaster 5000
      sentinel parallel-syncs mymaster 1
      sentinel failover-timeout mymaster 10000" > /etc/sentinel.conf &&
      redis-sentinel /etc/sentinel.conf'
    depends_on:
      - redis-master
      - redis-replica

Start the cluster:

docker-compose -f docker-compose.redis-sentinel.yml up -d

Configure Sockudo for Sentinel

Sockudo automatically discovers the current master from Sentinel nodes.In config/config.json:

{
  "adapter": {
    "driver": "redis"
  },
  "database": {
    "redis": {
      "sentinels": [
        { "host": "sentinel1.example.com", "port": 26379 },
        { "host": "sentinel2.example.com", "port": 26379 },
        { "host": "sentinel3.example.com", "port": 26379 }
      ],
      "sentinel_password": "optional-sentinel-auth",
      "name": "mymaster",
      "password": "redispass",
      "db": 0,
      "key_prefix": "sockudo:"
    }
  }
}

Configuration Options:

sentinels - Array of sentinel nodes with host and port
sentinel_password - Optional password for sentinel authentication
name - Master name monitored by sentinels (default: "mymaster")
password - Password for Redis master instance
username - Optional username for Redis ACL authentication

The connection URL is automatically built in the format:

redis+sentinel://[sentinelpass@]host1:port1,host2:port2/master-name/db[?password=masterpass]

Test Failover

# Simulate master failure
docker stop redis-master

# Watch Sentinel logs
docker logs -f sentinel1

# Sentinel will promote replica to master
# Sockudo will automatically reconnect to new master

# Verify Sockudo still works
curl http://localhost:6001/up/app-id

Redis Cluster

For multi-region or very high-traffic deployments (100K+ connections).

Architecture

┌─────────────┐  ┌─────────────┐  ┌─────────────┐
│  Master 1   │  │  Master 2   │  │  Master 3   │
│  (0-5460)   │  │ (5461-10922)│  │(10923-16383)│
└──────┬──────┘  └──────┬──────┘  └──────┬──────┘
       │                │                │
┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼──────┐
│  Replica 1  │  │  Replica 2  │  │  Replica 3  │
└─────────────┘  └─────────────┘  └─────────────┘

Create Redis Cluster

Using Docker Compose

Create docker-compose.redis-cluster.yml:

version: '3.8'

services:
  redis-node-1:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7001
    ports:
      - "7001:7001"

  redis-node-2:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7002
    ports:
      - "7002:7002"

  redis-node-3:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7003
    ports:
      - "7003:7003"

  redis-node-4:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7004
    ports:
      - "7004:7004"

  redis-node-5:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7005
    ports:
      - "7005:7005"

  redis-node-6:
    image: redis:7-alpine
    command: redis-server --cluster-enabled yes --cluster-config-file nodes.conf --cluster-node-timeout 5000 --appendonly yes --port 7006
    ports:
      - "7006:7006"

  redis-cluster-init:
    image: redis:7-alpine
    depends_on:
      - redis-node-1
      - redis-node-2
      - redis-node-3
      - redis-node-4
      - redis-node-5
      - redis-node-6
    command: >
      sh -c 'sleep 5 && redis-cli --cluster create
      redis-node-1:7001 redis-node-2:7002 redis-node-3:7003
      redis-node-4:7004 redis-node-5:7005 redis-node-6:7006
      --cluster-replicas 1 --cluster-yes'

Start cluster:

docker-compose -f docker-compose.redis-cluster.yml up -d

Configure Sockudo for Cluster

Set environment variables:

ADAPTER_DRIVER=redis-cluster
CACHE_DRIVER=redis-cluster
QUEUE_DRIVER=redis-cluster
RATE_LIMITER_DRIVER=redis-cluster

# Comma-separated list of cluster nodes
REDIS_CLUSTER_NODES=redis-node-1:7001,redis-node-2:7002,redis-node-3:7003

Or in config/config.json:

{
  "adapter": {
    "driver": "redis-cluster"
  },
  "cache": {
    "driver": "redis-cluster"
  },
  "queue": {
    "driver": "redis-cluster"
  },
  "rate_limiter": {
    "driver": "redis-cluster"
  },
  "database": {
    "redis_cluster": {
      "nodes": [
        "redis-node-1:7001",
        "redis-node-2:7002",
        "redis-node-3:7003"
      ],
      "password": "optional-password",
      "key_prefix": "sockudo:"
    }
  }
}

Verify Cluster

# Check cluster status
redis-cli -c -h localhost -p 7001 cluster info

# Check cluster nodes
redis-cli -c -h localhost -p 7001 cluster nodes

# Start Sockudo
./target/release/sockudo --features redis-cluster

# Test connection
curl http://localhost:6001/up/app-id

Connection Pooling

Sockudo automatically manages Redis connection pools.

Configuration

# Global pool settings (apply to all databases)
DATABASE_POOLING_ENABLED=true
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=10

# Redis-specific overrides
DATABASE_REDIS_POOL_MIN=4
DATABASE_REDIS_POOL_MAX=32

Or in config/config.json:

{
  "database_pooling": {
    "enabled": true,
    "min": 2,
    "max": 10
  },
  "database": {
    "redis": {
      "pool_min": 4,
      "pool_max": 32,
      "host": "localhost",
      "port": 6379
    }
  }
}

Sizing Guidelines

Connections	Pool Min	Pool Max
< 1,000	2	5
1K - 10K	4	10
10K - 50K	8	20
50K+	16	32

Performance Tuning

Redis Configuration

# /etc/redis/redis.conf

# Increase max connections
maxclients 10000

# Memory limit
maxmemory 4gb
maxmemory-policy allkeys-lru

# Persistence (disable for cache-only)
save ""
appendonly no

# Network buffer
tcp-backlog 511

# Disable slow log for performance
slowlog-log-slower-than -1

# Threading (Redis 6+)
io-threads 4
io-threads-do-reads yes

Sockudo Adapter Configuration

# Increase adapter buffer size
ADAPTER_BUFFER_MULTIPLIER_PER_CPU=128

# Connection pool
DATABASE_REDIS_POOL_MAX=32

Monitoring

Redis Metrics

# Connected clients
redis-cli -h localhost -p 6379 -a password INFO clients | grep connected_clients

# Memory usage
redis-cli -h localhost -p 6379 -a password INFO memory | grep used_memory_human

# Operations per second
redis-cli -h localhost -p 6379 -a password INFO stats | grep instantaneous_ops_per_sec

# Slow queries
redis-cli -h localhost -p 6379 -a password SLOWLOG GET 10

Sockudo Metrics

Sockudo exposes Redis adapter metrics via Prometheus:

curl http://localhost:9601/metrics | grep redis

Key metrics:

sockudo_adapter_publish_total - Messages published to Redis
sockudo_adapter_subscribe_total - Channel subscriptions
sockudo_adapter_errors_total - Redis connection errors

Troubleshooting

Connection Refused

Problem: Sockudo cannot connect to Redis. Solution:

Verify Redis is running: redis-cli -h localhost -p 6379 ping
Check firewall rules: sudo ufw allow 6379/tcp
Verify bind address in redis.conf: bind 0.0.0.0
Check credentials: redis-cli -h localhost -p 6379 -a password ping

Authentication Failed

Problem: NOAUTH Authentication required error. Solution:

Set password in Sockudo config: DATABASE_REDIS_PASSWORD=your-password
Or configure Redis without password (development only): comment out requirepass in redis.conf

High Memory Usage

Problem: Redis consumes too much memory. Solution:

Set memory limit: maxmemory 2gb in redis.conf
Enable eviction: maxmemory-policy allkeys-lru
Disable persistence if using Redis as cache only:
```
save ""
appendonly no
```
Clear old data: redis-cli FLUSHDB

Cluster Slot Errors

Problem: MOVED or ASK errors with Redis Cluster. Solution:

Sockudo handles cluster redirects automatically
If issues persist, rebuild cluster slot mapping:
```
redis-cli --cluster fix localhost:7001
```
Verify all nodes are reachable from Sockudo

Sentinel Failover Not Working

Problem: Sockudo doesn’t reconnect after Redis master fails. Solution:

Verify sentinel configuration includes all sentinels
Check sentinel quorum: need at least 2 sentinels agreeing
Ensure sentinel down-after-milliseconds is reasonable (5000ms)
Check Sockudo logs for reconnection attempts

Next Steps

Using with Nginx - Configure reverse proxy
Client Libraries - Connect clients to scaled deployment
Migrating from Pusher - Complete migration guide

Integration Guides

Operations

Documentation Index

​Why Use Redis with Sockudo?

​Redis Standalone

​Redis Sentinel (High Availability)

​Architecture

​Using Docker Compose

​Redis Cluster

​Architecture

​Using Docker Compose

​Connection Pooling

​Configuration

​Sizing Guidelines

​Performance Tuning

​Redis Configuration

​Sockudo Adapter Configuration

​Monitoring

​Redis Metrics

​Sockudo Metrics

​Troubleshooting

​Connection Refused

​Authentication Failed

​High Memory Usage

​Cluster Slot Errors

​Sentinel Failover Not Working

​Next Steps

Why Use Redis with Sockudo?

Redis Standalone

Redis Sentinel (High Availability)

Architecture

Using Docker Compose

Redis Cluster

Architecture

Using Docker Compose

Connection Pooling

Configuration

Sizing Guidelines

Performance Tuning

Redis Configuration

Sockudo Adapter Configuration

Monitoring

Redis Metrics

Sockudo Metrics

Troubleshooting

Connection Refused

Authentication Failed

High Memory Usage

Cluster Slot Errors

Sentinel Failover Not Working

Next Steps