Using the latest JFrog products?
JFrog Platform User Guide

Skip to end of metadata
Go to start of metadata


This page describes how to set up an Xray HA cluster with two or more nodes.



JFrog Xray HA is supported with an Enterprise License. JFrog Xray's license is enabled using the license of the Artifactory instances it's connected to.


Setting up an Xray HA cluster requires at least two Xray application nodes, each with the following minimal hardware requirements:

  • Processor: 8 cores
  • RAM: 16 GB
  • Storage: 100 GB

Minimum requirements

Note that these are minimum requirements for Xray to run. When Xray is used more intensively such as in larger installations or for scanning Docker images, RPM packages etc., you may need to provide more hardware resources.


  • Common Resources: Xray has three common resources:
    • PostgreSQL - Used to persist and navigate through the organization's components graph. This is either installed as part of the Xray installation or manually
    • MongoDB - Used to store components metadata and configuration. This is either installed as part of the Xray installation or manually.
    • RabbitMQ - Used to handle all microservices communication and to ensure no data loss. This is installed as part of the Xray installation and in case of HA architecture, RabbitMQ is also highly available using queue mirroring.
  • Load Balancer: The load balancer should be installed once all of he cluster nodes are up and running. It is the responsibility of your organization to manage and configure it correctly.


Externalising the PostgreSQL database

Xray HA requires an external PostgreSQL database. Make sure to install it before proceeding to install the first node. There are several ways to setup PostgreSQL for redundancy. Including: HA, Load Balancing and Replication. For more information, see the PostgreSQL documentation.

RabbitMQ is automatically installed as part of the Xray installation for every node. In case of HA architecture, it uses queue mirroring between the different RabbitMQ nodes, automatically setup.

Externalising the MongoDB database

Xray HA requires an external MongoDB database. Make sure to install it before proceeding to install the first node. There are several ways to setup MongoDB for redundancy. Including: HA, Load Balancing and Replication. 

General Guidelines

  • Nodes in a cluster must be installed with the same installation flavor
  • Nodes in a cluster must use the same databases
  • Nodes in a cluster must have a matching Xray version

Page Contents

Installing Xray HA

To get started, make sure your system complies with the above requirements and guidelines before you proceed to download and install Xray.

The general steps for installing Xray HA are:

  1. Prepare a valid license and two or more application servers
  2. In case you want to use your own database installation, prepare the databases and copy the connection strings
  3. Install/upgrade the first cluster node
  4. Copy the master key from the first cluster node
  5. Install the second cluster node providing the connection strings and master key
  6. Repeat step 5 to add additional nodes to your Xray cluster
  7. Setup a load balancer between the cluster nodes

Installing the First Node

Xray HA may be installed as a Docker image or as a native Linux installation for each of the supported flavors, according to the general Xray installation instructions.

During the first node installation, make sure to respond "No" to the "Are you adding this node to an existing cluster?" question.

Once you install/upgrade and run the first Xray node, a master.key file will be generated and saved in the security folder, located in the Xray data folder.

The Master key is a 32 bytes secret key that's used by Xray to securely synchronize the cluster nodes.

Installing Additional Nodes

The additional cluster nodes should also be installed according to the general Xray installation instructions.

Make sure to respond with a "Yes" to the "Are you adding this node to an existing cluster?" question at the beginning of the installation.

The installer will prompt you for the following additional information:

  • A 32 bytes master.key, found in <XRAY DATA FOLDER>/security/master.key of the initial node.
  • The short host name of the initial node, retrieved by using the 'hostname -s' command in the initial node.
  • database connection string, in order to connect to the same DB as the initial node.
    • For example: postgres://admin:password@<DatabaseHostname>:5432/xraydb?sslmode=disable
  • Enable full RabbitMQ HA clustering, by setting the host name of any of the active nodes in the HA cluster and not only to the active master node.

    Provide the short host name of an active cluster node (to retrieve it use the 'hostname -s' command):
  • During the installation process of the new node, you have an option to run a cluster cleanup.  If any of the nodes is down, you will be asked if you want to remove the node from the cluster.

    Looks like node '<NODE_NAME>' is NOT running. Would you like to remove node '<NODE_NAME>' from cluster? [y/n]:

    Please note that this will disconnect the node from the cluster. 

Migrating Xray From Standalone to HA

If you already have a working standalone Xray environment, you can easily migrate it to an HA environment.

This can be done by upgrading Xray to version 2.x (preferably the latest Xray version), as described here, and then treating it as the first cluster node. 

This means that once you have completed your upgrade, you can now add more nodes to your cluster by following the Installing Additional Nodes section described above.

The existing data and configuration you have in your current environment will not be harmed during the migration process, however, we do recommend backing up your data. 

  • No labels