ValKey as Redis Fork Installation

ValKey is a high-performance open-source fork of Redis, maintained by the Linux Foundation after Redis changed its license in 2024. ValKey is fully compatible with Redis 7.2 and is a true drop-in replacement for applications using Redis as a cache, session store, or message broker. This guide covers installing ValKey on Linux, configuring it, setting up clustering, and migrating from Redis.

Prerequisites

  • Ubuntu 20.04/22.04 or CentOS 8/Rocky Linux 8+
  • At least 1 GB RAM
  • Root or sudo access
  • For clustering: at least 3 nodes (6 for full HA)

Install ValKey on Linux

Ubuntu/Debian (official package):

# Add ValKey repository
curl -fsSL https://packages.valkey.io/valkey-archive.gpg | sudo gpg --dearmor -o /usr/share/keyrings/valkey.gpg

echo "deb [signed-by=/usr/share/keyrings/valkey.gpg] https://packages.valkey.io/deb $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/valkey.list

sudo apt update
sudo apt install -y valkey

sudo systemctl enable valkey-server
sudo systemctl start valkey-server

# Verify installation
valkey-cli ping
# PONG

valkey-cli info server | grep -E "valkey_version|redis_version"

CentOS/Rocky Linux:

# Add repository
cat > /etc/yum.repos.d/valkey.repo << 'EOF'
[valkey]
name=ValKey
baseurl=https://packages.valkey.io/rpm/el$releasever/$basearch
enabled=1
gpgcheck=1
gpgkey=https://packages.valkey.io/valkey-archive.gpg
EOF

sudo dnf install -y valkey
sudo systemctl enable --now valkey-server

Build from source (for latest version):

# Install build dependencies
sudo apt install -y build-essential tcl pkg-config libssl-dev

# Clone and build
git clone https://github.com/valkey-io/valkey.git
cd valkey
make -j$(nproc)
make test

sudo make install

# Verify
valkey-server --version

Docker:

docker run -d \
  --name valkey \
  -p 6379:6379 \
  -v valkey_data:/data \
  valkey/valkey:latest

docker exec valkey valkey-cli ping

Basic Configuration

ValKey uses the same configuration format as Redis:

# Default config location
sudo nano /etc/valkey/valkey.conf

Key configuration options:

# /etc/valkey/valkey.conf

# Network
bind 127.0.0.1 ::1
port 6379
protected-mode yes

# Authentication
requirepass your-strong-password-here

# Memory
maxmemory 2gb
maxmemory-policy allkeys-lru

# Persistence - RDB snapshots
save 900 1
save 300 10
save 60 10000
dir /var/lib/valkey
dbfilename dump.rdb

# AOF persistence
appendonly yes
appendfilename "appendonly.aof"
appendfsync everysec
no-appendfsync-on-rewrite no
auto-aof-rewrite-percentage 100
auto-aof-rewrite-min-size 64mb

# Logging
loglevel notice
logfile /var/log/valkey/valkey-server.log

# Connection limits
maxclients 10000
tcp-backlog 511
timeout 300
tcp-keepalive 300

sudo systemctl restart valkey-server

# Test
valkey-cli -a your-strong-password-here set foo bar
valkey-cli -a your-strong-password-here get foo

# Check configuration
valkey-cli -a your-password config get maxmemory
valkey-cli -a your-password config get maxmemory-policy

Replication Setup

Standard primary-replica replication:

# Primary server (server1: 192.168.1.10)
# No special config needed - primary by default
# Ensure bind and requirepass are set

# Replica server (server2: 192.168.1.11)
# Edit /etc/valkey/valkey.conf on server2:
replicaof 192.168.1.10 6379
masterauth your-primary-password
requirepass your-replica-password

# Restart the replica
sudo systemctl restart valkey-server

# Check replication status on primary
valkey-cli -h 192.168.1.10 -a your-primary-password info replication
# role:master
# connected_slaves:1
# slave0:ip=192.168.1.11,port=6379,state=online

# Check replica status
valkey-cli -h 192.168.1.11 -a your-replica-password info replication
# role:slave
# master_host:192.168.1.10
# master_link_status:up

ValKey Sentinel for automatic failover:

# Configure Sentinel on all 3 nodes
cat > /etc/valkey/sentinel.conf << 'EOF'
port 26379
sentinel monitor mymaster 192.168.1.10 6379 2
sentinel auth-pass mymaster your-primary-password
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1
logfile /var/log/valkey/sentinel.log
EOF

sudo chown valkey:valkey /etc/valkey/sentinel.conf

# Start Sentinel
valkey-sentinel /etc/valkey/sentinel.conf --daemonize yes

# Check Sentinel status
valkey-cli -p 26379 sentinel masters
valkey-cli -p 26379 sentinel slaves mymaster

Cluster Mode

ValKey cluster distributes data across multiple nodes:

# Create 6 instances on different ports (or different hosts)
# For testing: 3 primaries + 3 replicas on 6 ports

# Create config files for each instance
for port in 7000 7001 7002 7003 7004 7005; do
  mkdir -p /var/lib/valkey/cluster/${port}
  cat > /etc/valkey/cluster-${port}.conf << EOF
port ${port}
cluster-enabled yes
cluster-config-file /var/lib/valkey/cluster/${port}/nodes.conf
cluster-node-timeout 5000
appendonly yes
dir /var/lib/valkey/cluster/${port}
requirepass clusterpassword
masterauth clusterpassword
logfile /var/log/valkey/cluster-${port}.log
EOF
done

# Start all instances
for port in 7000 7001 7002 7003 7004 7005; do
  valkey-server /etc/valkey/cluster-${port}.conf --daemonize yes
done

# Create the cluster (3 primaries, 3 replicas)
valkey-cli --cluster create \
  127.0.0.1:7000 \
  127.0.0.1:7001 \
  127.0.0.1:7002 \
  127.0.0.1:7003 \
  127.0.0.1:7004 \
  127.0.0.1:7005 \
  --cluster-replicas 1 \
  -a clusterpassword

# Verify cluster
valkey-cli -p 7000 -a clusterpassword cluster info
valkey-cli -p 7000 -a clusterpassword cluster nodes

Migrate from Redis

ValKey is a drop-in replacement for Redis 7.2:

# Method 1: RDB file migration (fastest)

# Step 1: Create a snapshot on Redis
redis-cli -a redis-password BGSAVE
# Wait for completion
redis-cli -a redis-password LASTSAVE

# Step 2: Stop ValKey, copy RDB, start ValKey
sudo systemctl stop valkey-server
sudo cp /var/lib/redis/dump.rdb /var/lib/valkey/dump.rdb
sudo chown valkey:valkey /var/lib/valkey/dump.rdb
sudo systemctl start valkey-server

# Verify all keys migrated
valkey-cli -a your-password dbsize
# Should match: redis-cli -a redis-password dbsize

# Method 2: MIGRATE individual keys
# For selective migration or when services can't be stopped

redis-cli -a redis-password --scan | while read key; do
  redis-cli -a redis-password MIGRATE localhost 6380 "$key" 0 5000 AUTH your-valkey-password
done

# Method 3: Live replication
# Temporarily replicate from Redis to ValKey
# In /etc/valkey/valkey.conf:
# replicaof <redis-host> <redis-port>
# masterauth <redis-password>
# Let it sync, then promote to primary:
# valkey-cli replicaof NO ONE

Update application connection strings:

# Redis URL: redis://user:password@redis-host:6379
# ValKey URL: valkey://user:password@valkey-host:6379

# Or simply use the same Redis URL - ValKey responds to both
# Most clients (redis-py, ioredis, Jedis) work without any changes

Performance Comparison

# Benchmark ValKey
valkey-benchmark -a your-password -c 50 -n 500000 -q

# Compare output with Redis benchmark on same hardware
# redis-benchmark -a redis-password -c 50 -n 500000 -q

# Typical results show ValKey >= Redis 7.2 performance
# ValKey may add multi-threading improvements in future versions

# Test specific use cases
valkey-benchmark -a your-password -c 100 -n 1000000 -t set,get -q
valkey-benchmark -a your-password -c 50 -n 500000 -t lpush,lpop -q
valkey-benchmark -a your-password -c 50 -n 100000 -d 4096 -q  # large values

Client Compatibility

# Python - use redis-py (works with ValKey)
# pip install redis
import redis

# Connect to ValKey
r = redis.Redis(
    host='localhost',
    port=6379,
    password='your-password',
    decode_responses=True
)
r.set('key', 'value from valkey')
print(r.get('key'))

# All Redis commands work
r.lpush('queue', 'task1', 'task2', 'task3')
print(r.lrange('queue', 0, -1))

r.hset('user:1', mapping={'name': 'Alice', 'email': '[email protected]'})
print(r.hgetall('user:1'))

// Node.js with ioredis
const Redis = require('ioredis');
const client = new Redis({ host: 'localhost', port: 6379, password: 'your-password' });

client.set('greeting', 'Hello from ValKey').then(() => client.get('greeting')).then(v => {
  console.log(v);
  client.quit();
});

Troubleshooting

Service fails to start after migration from Redis:

# Check if Redis is still running on port 6379
ss -tlnp | grep 6379
sudo systemctl stop redis-server

# Check ValKey logs
sudo journalctl -u valkey-server -n 50
sudo tail -20 /var/log/valkey/valkey-server.log

RDB load error on startup:

# Check RDB file integrity
valkey-check-rdb /var/lib/valkey/dump.rdb

# If corrupt, try loading from AOF
# In valkey.conf: appendonly yes
# Remove the corrupt dump.rdb and restart to rebuild from AOF

Cluster nodes can't communicate:

# Check cluster bus port (command port + 10000)
# Port 7000 → cluster bus on port 17000
sudo ufw allow 17000:17005/tcp

# Check cluster health
valkey-cli --cluster check 127.0.0.1:7000 -a clusterpassword

High memory fragmentation:

# Check fragmentation ratio
valkey-cli -a your-password info memory | grep fragmentation

# Trigger active defragmentation
valkey-cli -a your-password config set activedefrag yes
valkey-cli -a your-password config set active-defrag-ignore-bytes 100mb
valkey-cli -a your-password config set active-defrag-threshold-lower 10

Conclusion

ValKey provides a fully compatible, open-source alternative to Redis under the Linux Foundation's stewardship, ensuring long-term community support without licensing concerns. It is a true drop-in replacement requiring only a binary swap and config copy from Redis. Deploy it as a primary-replica pair with Sentinel for production HA, use cluster mode for horizontal scaling, and migrate existing Redis workloads by copying the RDB snapshot file.