Valkey HA Installation ( Docker Compose )

Installation types:

Docker Compose

Supported from:

Xray version 3.150.9 and above
Catalog version: 1.42.1 and above

📘
Note
JFrog Xray, JFrog Catalog and JFrog Valkey are packaged in a single tarball for Docker installers. You will find the Valkey folder for the latest release version when you extract the Xray tarball. You can run Valkey either as a root user or as a non-root user.

Prerequisites

3 VMs (1 primary + 2 replicas)
TCP 6379 open between the three nodes
TCP 26379 open between the three nodes
Use the the same Valkey password on every node

Complete the following steps to install Valkey HA (Sentinel) with Docker Compose.

Docker Compose

First node (primary) installation steps

Download the latest Xray installer from here.
Extract the contents of the compressed Xray archive and go to the valkey folder.

tar -xvf jfrog-xray-<version>-compose.tar.gz
cd jfrog-valkey-compose/

Run the Valkey configuration script:

./config.sh

You will be prompted for configuration details. For the primary node, use:

Prompt	Value
Valkey password	Enter a password (or accept the default)
Valkey data path	Accept the default, or set a custom path
Deployment mode	`2` — sentinel (HA)
Primary or replica	`1` — primary
This node's IP address	This VM's IP (reachable by the other VMs)
Sentinel master name	Accept the default (`mymaster`), or set a custom name
Sentinel quorum	Accept the default (`2`)

Example session:

Fresh installation detected. Please provide configuration details:
Enter Valkey password (default: <default_password>):
Enter Valkey data path (default: /root/.jfrog/valkey):

Select deployment mode:
  1) standalone         - single Valkey node (default)
  2) sentinel (HA)      - one node of a 3-VM Valkey HA cluster with Sentinel
Enter your choice (1-2) [1]: 2

=== Valkey HA (Sentinel) configuration ===
Deploy this installer on 3 VMs: 1 primary + 2 replicas.

Is this node the primary or a replica?
  1) primary  (the first/master node)
  2) replica  (a secondary node that replicates from the primary)
Enter your choice (1-2) [1]: 1

Enter THIS node's IP address (reachable by the other VMs) (default: <THIS_NODE_IP>):

Enter the Sentinel master name (default: mymaster):

Enter the Sentinel quorum (default: 2):

On success, configuration is saved to .env and the installer reports:

Installation completed successfully!
Valkey is ready to be started.
start valkey:     docker-compose -p valkey -f docker-compose-valkey-sentinel.yaml up -d
stop valkey:      docker-compose -p valkey -f docker-compose-valkey-sentinel.yaml down

Start Valkey + Sentinel on the primary node:

docker-compose -p valkey -f docker-compose-valkey-sentinel.yaml up -d

Second and third nodes (replicas) installation steps

Repeat the download/extract steps on each replica VM, then run:

cd jfrog-valkey-compose/ 
./config.sh

For each replica node, use:

Prompt	Value
Valkey password	Same password as on the primary
Valkey data path	Accept the default, or set a custom path
Deployment mode	`2` — sentinel (HA)
Primary or replica	`2` — replica
This node's IP address	This VM's IP (reachable by the other VMs)
Primary node's IP address	The primary VM's IP
Sentinel master name	Same as on the primary (default: `mymaster`)
Sentinel quorum	Same as on the primary (default: `2`)

Example session:

Fresh installation detected. Please provide configuration details:
Enter Valkey password (default: <default_password>):
Enter Valkey data path (default: /root/.jfrog/valkey):

Select deployment mode:
  1) standalone         - single Valkey node (default)
  2) sentinel (HA)      - one node of a 3-VM Valkey HA cluster with Sentinel
Enter your choice (1-2) [1]: 2

=== Valkey HA (Sentinel) configuration ===
Deploy this installer on 3 VMs: 1 primary + 2 replicas.

Is this node the primary or a replica?
  1) primary  (the first/master node)
  2) replica  (a secondary node that replicates from the primary)
Enter your choice (1-2) [1]: 2

Enter THIS node's IP address (reachable by the other VMs) (default: <THIS_NODE_IP>):

Enter the PRIMARY node's IP address:
<PRIMARY_NODE_IP>

Enter the Sentinel master name (default: mymaster):

Enter the Sentinel quorum (default: 2):

Then start Valkey + Sentinel on each replica:

docker-compose -p valkey -f docker-compose-valkey-sentinel.yaml up -d

Connecting Catalog to Valkey HA

After all three nodes are running, add the following to Catalog's system.yaml (replace IPs / password), then start Catalog:

shared:
  cache:
    enabled: true
    connectionString: redis://<NODE1_IP>:26379,<NODE2_IP>:26379,<NODE3_IP>:26379
    parameters: mode=sentinel;password=<VALKEY_PASSWORD>;sentinelUseConnectionHosts=true

Replace <VALKEY_PASSWORD> with the Valkey password you configured (see VALKEY_PASSWORD in the generated .env file on any node).

Updated 15 days ago

Did this page help you?