Step-by-Step Redis Setup from Scratch: Docker, Docker Compose, Master‑Slave, Sentinel, and Cluster

Overview

This chapter aims to let a total beginner get Redis up and running while understanding every step. The roadmap is: start a single‑node Redis with Docker, manage the configuration with Docker Compose, then add master‑slave replication, Sentinel for automatic failover, and finally a sharded Redis Cluster. At the end a production configuration template and an online‑deployment checklist are provided.

1. Run a Single‑Node Redis with Docker

Start the simplest container:

docker run -d --name redis-lab -p 6379:6379 redis:7

Enter the container: docker exec -it redis-lab redis-cli Test the instance:

127.0.0.1:6379> PING
PONG
127.0.0.1:6379> SET hello world
OK
127.0.0.1:6379> GET hello
"world"

The minimal command works but has two problems: no password and no persistent data directory. Therefore we upgrade to a password‑protected, AOF‑enabled instance.

Upgrade to Password and Persistence

docker rm -f redis-lab

docker run -d \
  --name redis-standalone \
  -p 6379:6379 \
  -v "$(pwd)/redis-data:/data" \
  redis:7 redis-server \
  --requirepass 123456 \
  --appendonly yes

Verify persistence by setting a key, saving, restarting the container, and reading the key back:

docker exec -it redis-standalone redis-cli -a 123456 SET city shanghai
docker exec -it redis-standalone redis-cli -a 123456 SAVE
docker restart redis-standalone
docker exec -it redis-standalone redis-cli -a 123456 GET city
"shanghai"

2. Manage the Instance with Docker Compose

Create a directory and a docker-compose.yml that contains the same parameters as the manual docker run command, but makes the configuration reusable.

services:
  redis:
    image: redis:7
    container_name: redis-standalone
    ports:
      - "6379:6379"
    command:
      - redis-server
      - --requirepass 123456
      - --appendonly yes
    volumes:
      - ./data:/data
    restart: unless-stopped

Start and stop the stack with docker compose up -d and docker compose down -v. The ports mapping makes the service reachable on the host, while the bind‑mount keeps data after the container is removed.

3. Master‑Slave Replication (One Master, Two Slaves)

Replication solves single‑point‑of‑failure and read‑scaling problems. Create a new directory, write a docker‑compose.yml that defines three services: redis-master, redis-replica1, and redis-replica2. The master runs with a password; each replica uses --replicaof redis-master 6379 and the same password via --masterauth. Example snippet:

services:
  redis-master:
    image: redis:7
    container_name: redis-master
    ports:
      - "6379:6379"
    command:
      - redis-server
      - --requirepass 123456
      - --appendonly yes
    volumes:
      - ./data-master:/data

  redis-replica1:
    image: redis:7
    container_name: redis-replica1
    ports:
      - "6380:6379"
    command:
      - redis-server
      - --replicaof redis-master 6379
      - --requirepass 123456
      - --masterauth 123456
      - --appendonly yes
    volumes:
      - ./data-replica1:/data
    depends_on:
      - redis-master

  redis-replica2:
    image: redis:7
    container_name: redis-replica2
    ports:
      - "6381:6379"
    command:
      - redis-server
      - --replicaof redis-master 6379
      - --requirepass 123456
      - --masterauth 123456
      - --appendonly yes
    volumes:
      - ./data-replica2:/data
    depends_on:
      - redis-master

Validate the setup:

# Write on master
docker exec -it redis-master redis-cli -a 123456 SET course redis
# Read from replicas
docker exec -it redis-replica1 redis-cli -a 123456 GET course
docker exec -it redis-replica2 redis-cli -a 123456 GET course
# Attempt write on replica (should fail)
docker exec -it redis-replica1 redis-cli -a 123456 SET x 1
READONLY You can't write against a read only replica.

Newbie tip: Replication is asynchronous; a successful write on the master does not guarantee immediate visibility on replicas.

4. Sentinel for Automatic Failover

Sentinel monitors the master, decides when it is down, and promotes a replica to master. Create a directory redis-sentinel with three configuration files ( sentinel1.conf, sentinel2.conf, sentinel3.conf) that all contain:

# Sentinel port
port 26379

# Monitor a master named "mymaster"
sentinel monitor mymaster redis-master 6379 2

# Authentication for the master
sentinel auth-pass mymaster 123456

# Down‑after and failover timings
sentinel down-after-milliseconds mymaster 5000
sentinel failover-timeout mymaster 60000
sentinel parallel-syncs mymaster 1

# Resolve hostnames inside Docker network
sentinel resolve-hostnames yes
sentinel announce-hostnames yes

Compose file adds the three sentinel services, each mounting its own config file:

services:
  sentinel1:
    image: redis:7
    container_name: redis-sentinel1
    command: redis-sentinel /etc/redis/sentinel.conf
    volumes:
      - ./sentinel1.conf:/etc/redis/sentinel.conf
    depends_on:
      - redis-master
  # sentinel2 and sentinel3 are analogous

Start the stack, then verify that Sentinel sees the master:

docker exec -it redis-sentinel1 redis-cli -p 26379 SENTINEL master mymaster
docker exec -it redis-sentinel1 redis-cli -p 26379 SENTINEL get-master-addr-by-name mymaster

Simulate a failure by stopping the master container; after a few seconds Sentinel will promote one of the replicas. Verify the new master with the same SENTINEL get-master-addr-by-name command.

Newbie tip: Sentinel does not store data; it only controls failover. The data still lives on the promoted replica.

5. Redis Cluster (3 Masters, 3 Replicas)

When a single master cannot hold the data or write load, a sharded cluster distributes keys across 16384 hash slots. Create a directory redis-cluster and a docker‑compose.yml that defines six services (redis‑7001 … redis‑7006). Each node runs with:

command:
  - redis-server
  - --port 7001   # change per node
  - --cluster-enabled yes
  - --cluster-config-file nodes.conf
  - --cluster-node-timeout 5000
  - --appendonly yes
  - --requirepass 123456
  - --masterauth 123456

Ports expose both the client port (7001‑7006) and the cluster bus port (17001‑17006). After launching the six containers with docker compose up -d, create the cluster from any node:

docker exec -it redis-7001 redis-cli -a 123456 --cluster create \
  redis-7001:7001 redis-7002:7002 redis-7003:7003 \
  redis-7004:7004 redis-7005:7005 redis-7006:7006 \
  --cluster-replicas 1

Answer yes when prompted for slot allocation. The command makes the first three nodes masters and the remaining three replicas.

Validate the cluster:

# Cluster state
docker exec -it redis-7001 redis-cli -p 7001 -a 123456 CLUSTER INFO
# Nodes and slot distribution
docker exec -it redis-7001 redis-cli -p 7001 -a 123456 CLUSTER NODES
# Write a key in cluster mode (client follows MOVED redirects)
redis-cli -c -p 7001 -a 123456 SET user:1 Tom
redis-cli -c -p 7001 -a 123456 GET user:1
"Tom"

6. Installing Redis from Source

For traditional servers that do not use containers, compile Redis from source:

wget https://download.redis.io/releases/redis-7.2.4.tar.gz
 tar xzf redis-7.2.4.tar.gz
 cd redis-7.2.4
 make

The binaries appear in src/ ( redis-server, redis-cli). Start with a configuration file: src/redis-server redis.conf Optionally install system‑wide with sudo make install.

7. Production Configuration Templates

A conservative redis.conf template is provided. Key points:

Network: bind only to internal IP and 127.0.0.1; keep protected-mode yes.

Security: set a strong requirepass and optionally ACLs; rename dangerous commands (FLUSHALL, CONFIG, SHUTDOWN).

Process Management: daemonize yes and supervised systemd for systemd‑based deployments.

Persistence: enable AOF ( appendonly yes, appendfsync everysec) and configure RDB snapshots (e.g., save 900 1, save 300 10, save 60 10000).

Memory: set maxmemory to ~60% of RAM and choose maxmemory-policy allkeys-lru for cache workloads.

Replication Protection: masterauth, min-replicas-to-write 1, min-replicas-max-lag 10, and a sufficiently large repl-backlog-size.

Client Limits: tune maxclients and output‑buffer limits for normal, replica, and pub/sub clients.

8. Production Master‑Slave Settings

Master adds masterauth, min-replicas-to-write 1, min-replicas-max-lag 10, and a generous repl-backlog-size. Replicas configure replicaof, matching masterauth, and replica-read-only yes.

9. Production Sentinel Configuration

Each sentinel runs on port 26379, uses protected-mode yes, logs to /var/log/redis, and monitors the master with a quorum of 2 (for a 3‑sentinel deployment). Important parameters include down-after-milliseconds 10000, failover-timeout 180000, and parallel-syncs 1.

10. Production Deployment Checklist

Before going live, verify network isolation, strong passwords/ACLs, disabled dangerous commands, appropriate maxmemory, AOF/RDB strategy with recovery drills, master‑slave + sentinel failover, monitoring (INFO, slowlog, latency, replication status), regular backups, client connection‑pool settings, and absence of oversized keys.

11. Common Pitfalls and Troubleshooting

Cannot connect from host: ensure -p 6379:6379 mapping and that host port is free.

NOAUTH errors: authenticate with AUTH 123456 or use redis-cli -a 123456.

Replica cannot sync: verify --replicaof uses the Compose service name, and that requirepass and masterauth match.

Sentinel state inconsistent after failover: clean data directories and restore original sentinel*.conf before re‑running experiments.

Binding to 0.0.0.0 in production: avoid exposing Redis to the public internet; bind only to internal IPs and use firewalls/security groups.

Conclusion

This chapter takes Redis from zero to a fully‑featured deployment: a Docker‑based single node, a reusable Docker‑Compose setup, master‑slave replication, Sentinel‑driven automatic failover, and a sharded Redis Cluster. The tutorial emphasizes repeatable, clean environments for learning and highlights the additional hardening steps required for production, such as network restrictions, strong authentication, persistence tuning, high‑availability configuration, monitoring, and backup strategies.