Simplifying Redis Cluster Setup with Docker

By Ercan - 07/11/2025

When you work with Redis in cluster mode, local setup can quickly become a pain — especially when new developers join the team or when Redis is upgraded to a new version.
Traditionally, Redis cluster initialization requires building from source and running manual scripts. Each time the version changes, the build process has to be repeated, which isn’t ideal for agile teams or fast-paced projects.

In this article, I’ll share how I built a Redis cluster Docker image based on the official Redis image, allowing you to spin up a full cluster in seconds with a single docker run command.

1. The Traditional Way — Building Redis from Source

In our local environment, we used to build Redis manually from source and use the built-in cluster creation utility located under:

/utils/create-cluster

To start a cluster manually, you would typically run:

./create-cluster start

If it’s the first time, you also need to initialize the cluster:

./create-cluster create

After that, you can manage the cluster lifecycle using:

./create-cluster start
./create-cluster stop

This works fine, but maintaining it across multiple developers and Redis versions becomes cumbersome.

2. Why the Official Image Wasn’t Enough

While inspecting the official Redis Docker image, I noticed it removes all source files after the build process — including the create-cluster utility script.

That meant we couldn’t use the built-in create-cluster helper without building Redis ourselves again, defeating the purpose of using Docker for simplicity.

3. Extending the Official Image

To fix this, I created a custom Dockerfile that:

  1. Uses the official Redis image as a base.
  2. Copies the create-cluster script from Redis’s source repository.
  3. Adds a config.sh file to override certain defaults.
  4. Includes a custom entrypoint.sh that automatically starts the cluster when the container is launched.

Here’s how the configuration works internally:

  • The original create-cluster script expects Redis binaries under a relative BIN_PATH, which doesn’t match Docker’s directory structure.
  • It also runs Redis in protected mode by default (PROTECTED_MODE=yes), which prevents external access.

To fix these:

# config.sh
BIN_PATH="/usr/local/bin/"
PROTECTED_MODE=no

This way, the script runs smoothly inside the container environment.

4. Auto-Starting the Cluster

I created a small entrypoint script that automatically starts the cluster on container startup:

#!/bin/bash
/usr/local/bin/create-cluster start

So when the container is started, all 6 Redis nodes (3 masters, 3 replicas) are launched automatically using ports 30001–30006, as defined by the official create-cluster script.

5. Running the Cluster

To launch your local Redis cluster:

docker run -d -p 30001-30006:30001-30006 \
  --name redis-cluster \
  ercansormaz/redis-cluster

Then, initialize the cluster once:

docker exec -it redis-cluster create-cluster create

From that point on, you can start and stop the cluster as needed:

docker container start redis-cluster
docker container stop redis-cluster

6. Notes on Usage

This image is designed for local development and testing.
It runs multiple Redis instances (nodes) within a single container, which is not recommended for production environments.
For production setups, always run each node on a separate machine or container to ensure real high availability and fault tolerance.

7. Conclusion

By simply extending the official Redis image and restoring the create-cluster script, we can now spin up a full Redis cluster in seconds — without building from source or handling complex configurations.

If you want to try it yourself, the image is available on Docker Hub:
👉 ercansormaz/redis-cluster

It’s a small change, but it makes onboarding and local testing significantly faster for teams working with Redis clusters.

Tags: redis, docker