How to Set Up a Redis Cluster on macOS

1. Why build a Redis cluster

Redis stores all data in memory, so the amount of data it can hold is limited by the server's RAM; a 64 GB server can store at most 64 GB of data, which is insufficient for large‑scale websites that may need terabytes of storage. Before Redis 3.0, keys were assigned to nodes using a simple hash‑modulo method, which does not support dynamic scaling because adding or removing nodes would break key placement. Starting with Redis 3.0, the cluster mode uses hash slots, allowing multiple Redis instances to be combined into a cluster where each node knows the slots it is responsible for, enabling horizontal scaling without a single point of failure.

Example: after setting a key cluster7001 with value "test" on port 7001, Redis redirects the client to the correct node and slot (e.g., slot 1391).

Redis indicates the proper node (7001) and slot for the key.

2. Setting up a Redis cluster on macOS

To run a Redis cluster you need at least three master nodes; this tutorial creates six nodes (three masters and three slaves) using ports 7001‑7006.

Step 1: Download and install Redis

Download the latest Redis version from the official website.

Step 2: Create the cluster directory

Navigate to the Redis installation directory and create a folder for the cluster:

sudo mkdir redis-cluster

Enter the folder and create six sub‑folders for the nodes:

mkdir redis01

mkdir redis02

mkdir redis03

mkdir redis04

mkdir redis05

mkdir redis06

Step 3: Modify the configuration file

Edit redis.conf in each node folder and set the following options:

port 7001 # port number

daemonize yes # run as a background daemon

cluster-enabled yes # enable cluster mode

cluster-config-file nodes.conf # node configuration file

cluster-node-timeout 5000 # timeout in milliseconds

appendonly yes # enable AOF persistence

After editing, copy the modified redis.conf to each of the six node directories and ensure the port numbers match (7001‑7006). Also copy the redis-server binary from the Redis src directory into each node folder.

Each node folder should now contain the configuration file and the server binary.

Step 4: Start the six Redis instances

Open a terminal and run the following commands for each node:

cd /usr/local/redis/redis-cluster/redis01/

sudo redis-server redis.conf

Repeat the same for redis02 … redis06 .

Verify that all instances are running:

ps -ef | grep redis

You should see six Redis processes.

At this point the instances are running independently; they still need to be linked into a cluster.

Step 5: Install Ruby gem for cluster management

Redis cluster creation uses the redis-trib.rb script, which requires Ruby ≥ 1.8.7. Check the Ruby version (e.g., 2.0.0) and install the gem:

gem install redis

Installation should succeed.

Step 6: Create the Redis cluster

Navigate to the Redis src directory and run the cluster creation command:

./redis-trib.rb create --replicas 1 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 127.0.0.1:7006

The command will output the cluster status and confirm that the cluster has been created.

Step 7: Test the cluster

From the src directory, use the cluster‑aware CLI:

redis-cli -c -p 7001

Set a test key:

set test yeah

The key should be visible on both the master (7001) and its replica (7004), confirming that the cluster is functioning correctly.