Redis Cluster: First-Time Setup Guide

Everything you need to connect, verify, and start using your Redis Cluster instance purchased from the HostGraber Marketplace. No prior Redis cluster experience required.

Read time: ~8 minutes

Applies to: Redis 7 Cluster (6-node)

Updated: June 2026

01. What your deployment includes

When you deploy Redis Cluster from the HostGraber Marketplace, the server automatically provisions a production-ready 6-node Redis Cluster using Docker. No manual installation is needed.

The following services are running by the time your server is ready (2 to 3 minutes after first boot):

Cluster Topology

+ RedisInsight web GUI on port 80 (proxied via Nginx)

All 16,384 hash slots are distributed evenly across the three primaries. Each primary has exactly one replica for automatic failover. The entire cluster is bootstrapped and slot-assigned before the server is marked as ready.

02. Finding your credentials

All connection details are written to a file on your server the moment setup completes. SSH into your server and read the file:

$ ssh root@YOUR_SERVER_IP
$ cat /root/credential.txt

The file contains your server IP, Redis password, all node addresses, RedisInsight URL, and management commands.

Security notice: > Delete this file after you have saved your credentials. Run shred -u /root/credential.txt to securely remove it. The password is not stored anywhere else on the server, so save it in a password manager before deleting.

If the file does not exist yet, setup may still be running. Watch the log in real time:

$ tail -f /var/log/redis-cluster-setup.log

Setup takes roughly 3 to 5 minutes. The final line reads === Setup complete when finished.

03. Cluster topology and ports

Your firewall is pre-configured. Here is a reference for all open ports:

About the cluster bus ports: > Ports 17001 through 17006 are the Redis cluster gossip bus. Each node's bus port is its data port plus 10,000. These ports handle node discovery, health checks, and failover signaling. Your application never connects to these directly.

04. Verifying the cluster is healthy

Before connecting your application, confirm that all six nodes are online and the cluster state is ok. Run this from the server:

docker exec redis-7001 redis-cli -p 7001 -a 'YOUR_PASSWORD' cluster info

Look for these two lines in the output:

cluster_state:ok
cluster_known_nodes:6

To see all six nodes and their assigned slots:

docker exec redis-7001 redis-cli -p 7001 -a 'YOUR_PASSWORD' cluster nodes

If cluster_state is not ok: > Wait two minutes and try again. If it remains in an error state, check the setup log with tail -50 /var/log/redis-cluster-setup.log and look for any error message during the bootstrap step.

05. Connecting RedisInsight (web GUI)

RedisInsight is a free browser-based interface for browsing keys, running commands, inspecting memory usage, and monitoring cluster health. It is already running on your server.

Open the interface

Navigate to http://YOUR_SERVER_IP in your browser.

Add your cluster connection

On first load, RedisInsight asks you to add a database. Follow these steps:

1. Click Add Redis Database.

2. Select Redis Cluster as the connection type.

3. Enter any single node as the seed: host YOUR_SERVER_IP, port 7001.

4. Enter your Redis password in the Password field.

5. Click Add Database. RedisInsight will auto-discover all 6 nodes.

Success indicator: > After connecting, you will see a cluster overview listing all 6 nodes with their shard assignments, memory usage, and status. A green indicator means all nodes are reachable.

06. Connecting via redis-cli

The -c flag is required when using redis-cli with a cluster. It enables cluster mode, which means the client will automatically follow MOVED redirects when a key lives on a different shard.

From inside the server (Docker)

docker exec -it redis-7001 redis-cli -c -p 7001 -a 'YOUR_PASSWORD'

From a remote machine

redis-cli -c -h YOUR_SERVER_IP -p 7001 -a 'YOUR_PASSWORD'

Quick test (Interactive)

127.0.0.1:7001> SET testkey "hello"
-> Redirected to slot [4205] located at 117.252.16.15:7001
OK
127.0.0.1:7001> GET testkey
"hello"
127.0.0.1:7001> PING
PONG

The redirect message is normal. It shows which shard accepted the key based on its computed hash slot.

07. Connecting from your application

Use any seed node (ports 7001, 7002, or 7003) to bootstrap. The client library will auto-discover all remaining nodes. Always use a cluster-aware client, not a plain Redis client.

Node.js — ioredis

const Redis = require('ioredis');

const cluster = new Redis.Cluster([
  { host: 'YOUR_SERVER_IP', port: 7001 },
  { host: 'YOUR_SERVER_IP', port: 7002 },
  { host: 'YOUR_SERVER_IP', port: 7003 },
], {
  redisOptions: { password: 'YOUR_PASSWORD' }
});

await cluster.set('hello', 'world');
const val = await cluster.get('hello');
console.log(val); // world

Python — redis-py

from redis.cluster import RedisCluster

r = RedisCluster(
    startup_nodes=[{"host": "YOUR_SERVER_IP", "port": 7001}],
    password="YOUR_PASSWORD",
    decode_responses=True
)

r.set("hello", "world")
print(r.get("hello"))  # world

PHP — Predis

use Predis\Client;

$client = new Client([
    ['host' => 'YOUR_SERVER_IP', 'port' => 7001],
    ['host' => 'YOUR_SERVER_IP', 'port' => 7002],
    ['host' => 'YOUR_SERVER_IP', 'port' => 7003],
], [
    'cluster'    => 'redis',
    'parameters' => ['password' => 'YOUR_PASSWORD'],
]);

$client->set('hello', 'world');
echo $client->get('hello'); // world

Connection URI format

redis://:YOUR_PASSWORD@YOUR_SERVER_IP:7001

You can use any of ports 7001, 7002, or 7003 as the seed. Pass all three when your client supports multiple seed nodes for better resilience.

08. How keys work in cluster mode

Redis Cluster distributes keys across shards based on a CRC16 hash of the key name. This works transparently for most operations, but there are two important rules to understand before building your application.

Rule 1: multi-key commands require same-slot keys

Commands that operate on multiple keys at once — such as MGET, MSET, MULTI/EXEC transactions, and Lua scripts — only work when all involved keys hash to the same slot. If they are on different nodes, Redis returns a CROSSSLOT error.

redis-cli — this will fail:

> MSET user:1 "alice" user:2 "bob"
(error) CROSSSLOT Keys in request don't hash to the same slot

Rule 2: use hash tags to force keys onto the same slot

Wrap the shared part of the key in curly braces {}. Redis uses only the content inside the braces to compute the slot, so all keys with the same tag land on the same node.

redis-cli — correct approach:

> MSET {user}:1 "alice" {user}:2 "bob"
OK
> MGET {user}:1 {user}:2
1) "alice"
2) "bob"

Practical naming convention: > Use the object type or tenant ID as the hash tag. For example: {session}:abc123, {order}:9982, {tenant:42}:settings. Keys in the same logical group share a tag; keys in different groups have separate tags to spread load evenly.

09. Day-to-day management commands

All commands below are run from your server over SSH.

Persistent data: > Each node stores its data in /opt/redis-cluster/node-700X/data/ on the host. Both AOF (append-only file) and RDB snapshots are enabled by default. Data survives container restarts and server reboots.

10. Next steps and hardening

Your cluster is functional out of the box. These steps are recommended before putting it into production.

Enable HTTPS for RedisInsight

apt install certbot python3-certbot-nginx
certbot --nginx -d your.domain.com

You must point a DNS A record to your server IP first. Once HTTPS is active, RedisInsight will be available at https://your.domain.com.

Restrict Redis access by IP

By default, ports 7001 through 7006 are open to the internet. If your application server has a fixed IP, add a firewall rule to restrict access:

# Allow only your app server
ufw allow from YOUR_APP_SERVER_IP to any port 7001:7006 proto tcp

# Remove the open rule
ufw delete allow 7001/tcp
# (repeat for 7002-7006)

Set a maxmemory limit

To prevent Redis from consuming all available RAM, add a memory cap to each node's /opt/redis-cluster/node-700X/redis.conf:

maxmemory 1gb
maxmemory-policy allkeys-lru

After editing, restart the affected container: docker restart redis-7001 (repeat for each node).

Secure deletion of credentials file

shred -u /root/credential.txt

You are ready > Your Redis Cluster is live, verified, and connected. For further reading, visit the HostGraber Knowledge Base or browse other products on the HostGraber Marketplace.