Valkey HA Installation ( RPM / Deb / Archive )

Installation types:

• RPM or Debian
• Linux Archive

Supported from:

• Xray version 3.150.20 and above
• Catalog version: 1.37.2 and above

Prerequisites

• 3× RHEL9 hosts (1 primary + 2 replicas)
• TCP 6379 open between the three nodes
• TCP 26379 open between the three nodes

Installation Steps

Complete the following steps to install the product.

RPM / Deb / Linux Archive

First node (primary) installation steps

1. SSH into the primary node

ssh -i ~/.ssh/<your-key>.pem root@<primary-node-ip>

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

tar -xvf jfrog-xray-<version>-<linux/rpm/deb>.tar.gz
cd jfrog-xray-<version>-<linux/rpm/deb>/

4. Rename the valkey folder

mv jfrog-valkey-linux valkey/

5. Run the Valkey installation script:

cd valkey/valkey-<OS_FLAVOUR>/app/bin/
./install-valkey-service.sh

You will be prompted for:

1. Deployment mode — select 2) sentinel (HA).
2. Valkey password — required in HA mode. Use the same password on all three nodes.
3. This node's IP — the primary node's IP, reachable by the other VMs (a detected default is offered when available).
4. Node role — select 1) primary.
5. Sentinel master name — default mymaster (press Enter to accept).
6. Sentinel quorum — default 2 (press Enter to accept).

The installer writes the bind address, masterauth, and Sentinel settings automatically, and installs the valkey and valkey-sentinel systemd units.

6. Start Valkey and Sentinel:

systemctl start valkey
systemctl start valkey-sentinel

7. Verify Sentinel is running:

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-cli -p 26379 INFO sentinel

You should see:

master0:name=mymaster,status=ok,address=<PRIMARY_NODE_IP>:6379,slaves=0,sentinels=1

Additional node (replica) installation steps

Complete the following steps on each secondary node. Install the primary first, then the two replicas.

1. SSH into the secondary node

ssh -i ~/.ssh/<your-key>.pem root@<secondary-node-ip>

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

tar -xvf jfrog-xray-<version>-<linux/rpm/deb>.tar.gz
cd jfrog-xray-<version>-<linux/rpm/deb>/

4. Rename the valkey folder

mv jfrog-valkey-linux valkey/

5. Run the Valkey installation script. Provide the same password as the primary node when prompted.

cd valkey/valkey-<OS_FLAVOUR>/app/bin/
./install-valkey-service.sh

You will be prompted for:

1. Deployment mode — select 2) sentinel (HA).
2. Valkey password — must match the primary.
3. This node's IP — the secondary node's IP, reachable by the other VMs.
4. Node role — select 2) replica.
5. Primary node's IP — the IP of the primary installed above.
6. Sentinel master name — use the same value as the primary (default mymaster).
7. Sentinel quorum — use the same value as the primary (default 2).

The installer configures replicaof, masterauth, bind, and Sentinel, and installs both systemd units.

6. Start Valkey and Sentinel:

systemctl start valkey
systemctl start valkey-sentinel

7. Verify replication on the replica:

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-cli -a <valkey-password> INFO replication

Look for role:slave and master_link_status:up.

8. Verify Sentinel:

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-cli -p 26379 INFO sentinel

After the first replica joins, you should see something like:

master0:name=mymaster,status=ok,address=<PRIMARY_NODE_IP>:6379,slaves=1,sentinels=2

9. Repeat the exact same steps on the third node, then do a final verification on the primary:

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-cli -a <valkey-password> INFO replication

You should see connected_slaves:2 once both replicas are connected.

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-cli -p 26379 INFO sentinel

You should see slaves=2,sentinels=3:

master0:name=mymaster,status=ok,address=<PRIMARY_NODE_IP>:6379,slaves=2,sentinels=3

Connecting with Catalog

Before starting up catalog, add cache section to the system.yaml of catalog.

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

The password parameter authenticates Catalog to the Valkey data nodes. It is not used when connecting to the Sentinel processes.

When connecting Catalog to a Valkey Sentinel cluster:

• Leave Sentinel authentication disabled. A cluster installed using the steps above is configured this way by default, so no additional action is required.
• Keep requirepass set on the Valkey data nodes. Cached data remains password protected through the password parameter.
• Restrict access to the Sentinel port at the network layer. Allow TCP 26379 only between the three Valkey nodes and your Catalog nodes, using security groups, firewall rules, or a private subnet.

This also applies when you enable Curation for Cached Packages, which uses a Valkey Sentinel cluster for high availability.

Related Topics

• Catalog Installation
• Catalog Installation with Interactive Script
• Catalog Helm and OpenShift Installation
• PostgreSQL for JFrog Catalog
• Product Dependencies Matrix