How to Build a Redis Cluster with Docker: Step‑by‑Step Guide

Since I started using Docker, I have tried to containerize every service I need, and in this article I will show how to build a Redis Cluster with Docker.

Redis Cluster is Redis's distributed solution that maps keys to virtual slots (0‑16383) using the CRC16 hash function: slot = CRC16(key) & 16383. Each node is responsible for a subset of slots.

1. Create the Redis base Docker image

1. Download Redis source (version 4.0.1)

[root@etcd1 tmp]# mkdir docker_redis_cluster
[root@etcd1 tmp]# cd docker_redis_cluster/
[root@etcd2 docker_redis_cluster]# wget http://download.redis.io/releases/redis-4.0.1.tar.gz

2. Extract and compile

[root@etcd1 docker_redis_cluster]# tar zxvf redis-4.0.1.tar.gz
[root@etcd1 docker_redis_cluster]# cd redis-4.0.1/
[root@etcd1 redis-4.0.1]# make

3. Modify the configuration

# bind 0.0.0.0
daemonize no
requirepass 123456
masterauth 123456
logfile /var/log/redis/redis-server.log
cluster-enabled yes
cluster-config-file nodes-6379.conf
cluster-node-timeout 15000

2. Build the base image

FROM centos:7
ENV REDIS_HOME /usr/local
ADD redis-4.0.1.tar.gz /
RUN mkdir -p $REDIS_HOME/redis
ADD redis-4.0.1/redis.conf $REDIS_HOME/redis/
RUN yum -y update && yum install -y gcc make
WORKDIR /redis-4.0.1
RUN make
RUN mv /redis-4.0.1/src/redis-server $REDIS_HOME/redis/
RUN rm -rf /redis-4.0.1
RUN yum remove -y gcc make
VOLUME [/var/log/redis]
EXPOSE 6379

Note: the image does not contain ENTRYPOINT or CMD.

3. Build the Redis node image

FROM hakimdstx/cluster-redis:4.0.1
MAINTAINER hakim [email protected]
ENTRYPOINT ["/usr/local/redis/redis-server", "/usr/local/redis/redis.conf"]

4. Run the containers

# Start six containers (ports 6379‑6384)
[root@etcd3 docker_redis_nodes]# docker run -d --name redis-6379 -p 6379:6379 hakimdstx/nodes-redis:4.0.1
[root@etcd3 docker_redis_nodes]# docker run -d --name redis-6380 -p 6380:6379 hakimdstx/nodes-redis:4.0.1
... (repeat for 6381‑6384)

Check the containers with docker ps and note their internal IPs (172.17.0.2‑0.7).

5. Form the cluster

Make each node meet the others:

# Example for the first node
192.168.10.52:6379> CLUSTER MEET 172.17.0.3 6379
... (repeat for all nodes)

Initially the cluster state is fail because no slots are assigned.

6. Assign hash slots

Use a script (addslots.sh) to distribute the 16384 slots among the three master nodes:

#!/bin/bash
# node1 0‑5461
for i in {0..5461}; do
  /usr/local/bin/redis-cli -h 192.168.10.52 -p 6379 -a 123456 CLUSTER ADDSLOTS $i
done
# node2 5462‑10922
for i in {5462..10922}; do
  /usr/local/bin/redis-cli -h 192.168.10.52 -p 6380 -a 123456 CLUSTER ADDSLOTS $i
done
# node3 10923‑16383
for i in {10923..16383}; do
  /usr/local/bin/redis-cli -h 192.168.10.52 -p 6381 -a 123456 CLUSTER ADDSLOTS $i
done

After the script runs, CLUSTER INFO shows cluster_state:ok and all slots assigned.

7. Add replica nodes

Use another script (addSlaveNodes.sh) to turn the remaining three containers into slaves of the masters:

/usr/local/bin/redis-cli -h 192.168.10.52 -p 6382 -a 123456 CLUSTER REPLICATE 760e4d0039c5ac13d04aa4791c9e6dc28544d7c7
/usr/local/bin/redis-cli -h 192.168.10.52 -p 6383 -a 123456 CLUSTER REPLICATE 54cb5c2eb8e5f5aed2d2f7843f75a9284ef6785c
/usr/local/bin/redis-cli -h 192.168.10.52 -p 6384 -a 123456 CLUSTER REPLICATE f45f9109f2297a83b1ac36f9e1db5e70bbc174ab

The cluster now has three masters and three slaves, providing high availability.

8. Test failover

Stop one master (e.g., the container on port 6380). The cluster initially reports cluster_state:fail because the slave cannot authenticate (missing masterauth). After adding masterauth 123456 to the slave configuration and restarting, the slave promotes itself automatically.

If manual failover is needed, run on a slave: CLUSTER FAILOVER FORCE The slave becomes a master, and the original master (when restarted) joins as a replica.

9. Access the cluster

Clients only need to know one node address; the cluster will redirect commands with MOVED replies to the correct node. Only database 0 is usable; SELECT other DBs returns an error.

10. Network considerations for production

When containers run on different hosts, use Docker's --net host mode and bind each Redis instance to a unique host port (e.g., 60001, 60002, …). Mount a host‑specific configuration file into the container to avoid port conflicts. Ensure firewalls allow the required ports.

With these steps, a fully functional, highly available Redis Cluster running in Docker is ready for production use.