Valkey HA Installation

Installation types:

• RPM or Debian
• Linux Archive

Supported from:

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

📘

Note

JFrog Xray, JFrog Catalog and JFrog Valkey are packaged in a single tarball for RPM/Deb and Linux 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× RHEL9 hosts (1 primary + 2 replicas )
• TCP 6379 open between the three nodes
• TCP 26379 open between the three nodes

Complete the following steps to install the product.

RPM / Deb / Linux Archive

First node 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:
   You will be prompted to create a password for Valkey.

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

6. Before setting up replicas, the primary node must be configured to accept connections from other machines. By default, Valkey binds only to localhost (127.0.0.1), which prevents replicas from connecting.
   1. Open the Valkey configuration file
   bash

   vi valkey/valkey-<OS_FLAVOUR>/var/etc/valkey.conf

   b. Locate the bind directive and update it to include the primary node’s own IP address:
   bash

   bind 127.0.0.1 `<PRIMARY_NODE_IP>`

7. Start the valkey service:
   bash

   systemctl start valkey

8. Create the Sentinel configuration file:
   bash

   vi valkey/valkey-<OS_FLAVOUR>/var/etc/sentinel.conf

9. Add the following content:
   Replace <PRIMARY_NODE_IP> with the primary node IP and <valkey-password> with your actual password.

# Sentinel port
port 26379

# Monitor the primary node
# "mymaster" is the master name — your application will use this name to connect
# 2 = quorum (number of Sentinels that must agree the primary is down before failover)
sentinel monitor mymaster <PRIMARY_NODE_IP> 6379 2

# Password for the primary (and replicas, since they share the same password)
sentinel auth-pass mymaster <valkey-password>

# How long (ms) the primary must be unreachable before marking it as down
sentinel down-after-milliseconds mymaster 5000

# Timeout (ms) for the failover process
sentinel failover-timeout mymaster 60000

# How many replicas can sync from the new primary simultaneously during failover
sentinel parallel-syncs mymaster 1

# Log file
logfile "valkey/valkey-<OS_FLAVOUR>/var/logs/sentinel.log"

# Run as daemon
daemonize yes

# PID file

10. Start Sentinel

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-server valkey/valkey-<OS_FLAVOUR>/var/etc/sentinel.conf --sentinel

11. Verify Sentinel is running

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

12. You should see this:

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

Additional node installation steps

Complete the following steps to install valkey on each secondary node.

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:
   You will be prompted to create a password for Valkey. Provide the same password when prompted as the primary node.

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

6. Before starting up replicas, the secondary node must be configured to accept connections from other machines.
   1. Open the Valkey configuration file on the secondary node:
   bash

   vi valkey/valkey-<OS_FLAVOUR>/var/etc/valkey.conf

   b. Locate the bind directive and update it to include the secondary node’s own IP address:
   bash

   bind 127.0.0.1 `<SECONDARY_NODE_IP>`

   c. Add the following lines to the end of valkey.conf file in the secondary node:
   YAML

   6. replicaof <SECONDARY_NODE_IP> 6379
      masterauth <primary-node-password>

7. Start the valkey service:

systemctl start valkey

6. Verify replication
   bash

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

   Look for role:slave and master_link_status:up.
7. Create the Sentinel configuration file:

vi valkey/valkey-<OS_FLAVOUR>/var/etc/sentinel.conf

9. Add the following content:

Replace _<PRIMARY_NODE_IP>_ with the primary node IP and <valkey-password> with your actual password.

# Sentinel port
port 26379

# Monitor the primary node
# "mymaster" is the master name — your application will use this name to connect
# 2 = quorum (number of Sentinels that must agree the primary is down before failover)
sentinel monitor mymaster <PRIMARY_NODE_IP> 6379 2

# Password for the primary (and replicas, since they share the same password)
sentinel auth-pass mymaster <valkey-password>

# How long (ms) the primary must be unreachable before marking it as down
sentinel down-after-milliseconds mymaster 5000

# Timeout (ms) for the failover process
sentinel failover-timeout mymaster 60000

# How many replicas can sync from the new primary simultaneously during failover
sentinel parallel-syncs mymaster 1

# Log file
logfile "valkey/valkey-<OS_FLAVOUR>/var/logs/sentinel.log"

# Run as daemon
daemonize yes

# PID file
pidfile "valkey/valkey-<OS_FLAVOUR>/var/logs/sentinel.pid"

10. . Start Sentinel

valkey/valkey-<OS_FLAVOUR>/app/bin/valkey-server   
valkey/valkey-<OS_FLAVOUR>/var/etc/sentinel.conf --sentinel

11. 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=1,sentinels=2.

12. Now repeat the exact same steps on the third node, and then do a final verification on the primary node:

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

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

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

You should see slaves=2,sentinels=3 once both replicas are connected.

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 

📘

Notes:

• For removing Valkey in RPM/ Deb/ Linux Archive installers, navigate to valkey/app/bin and run ./uninstall-valkey-service.sh. This will remove everything but the valkey configuration file.
• The Valkey service includes automatic log rotation to manage log file sizes and prevent disk space issues. Logs are by default rotated when they reach 25MB, keeping up to 10 rotated files with compression. Old logs are moved to an archived directory valkey/var/logs/archived with timestamped filenames.