Upgrading via installV2.sh ( Xray Version >= 3.131.x )

Prerequisites

Before upgrading Xray and migrating to Quorum Queue, ensure the following:

1. Existing Xray deployment — A running Xray single-node or HA instance installed via RPM, Debian, Linux archive, or Docker Compose.
2. Xray version 3.131.x or later — The installV2.sh / configV2.sh script and Quorum Queue support are only available from this version onward.
3. RabbitMQ version 3.11.x or higher — Your existing deployment must already be on RabbitMQ 3.11.x or higher before enabling Quorum Queue or upgrading to RabbitMQ 4.

📘

Awareness of the two-step migration — Migrating to RabbitMQ 4 + Quorum Queue is a two-run process: the first run optionally enables Quorum Queue on RabbitMQ 3, and the second run optionally upgrades to RabbitMQ 4. Plan a maintenance window accordingly.

The Big Picture

Upgrading from Xray Version 3.131.x to 3.131.x or above

RPM, Debian, or Docker Compose

Starting Xray version 3.131.x, the installer script will allow you to install RabbitMQ 4 and/or Quorum queues, optionally.

The installer script works with all supported upgrade methods (RPM, Debian, and Docker Compose). It provides you an interactive way to upgrade Xray and its dependencies.

Stage 1

1. Download Xray (RPM, Debian, or Docker Compose).

2. Stop the service.

   systemd OS

   Bash

   systemctl stop xray.service

   systemv OS

   Bash

   service xray stop

   Docker Compose

   Bash

   cd jfrog-xray-<version>-compose
   docker-compose -p xray down

3. Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.

   Bash

   tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
   cd jfrog-xray-<version>-<compose|rpm|deb>

   Note: For Docker Compose upgrades, make sure to merge any customizations in your current docker-compose.yaml file to the new extracted version of the docker-compose.yaml file.

   Note: Copy the contents of the .env file in the previous installation to the newly created .env file in this archive without copying the versions, as this will affect the upgrade.

Stage 2

1. Run the installer script.

   If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL), joinKey and the Rabbitmq Quorum queue or version migration.

   Compose

   Bash

   ./configV2.sh

   RPM/DEB

   Bash

   ./installV2.sh

a. Upgrading to RabbitMQ and the Quorum queue is a 2-step process. The first time you run the upgrade script, it will ask you to optionally enable Quorum Queue with RabbitMQ3

Verification of Quorum Queue Migration

b. After completing the above, you should wait for the quorum migration to complete. Follow these steps to verify:

1. Refer Troubleshooting on the Xray-RabbitMQ Quorum Queue migration

2. Look for these logs in the xray-server.log:

RabbitMQ migration migrate_msgs_from_other_rabbitmq completed successfully
RabbitMQ migration delete_classic_queues_vhost completed successfully

Stage 3

c. The next time you run the same script, it will optionally ask you to upgrade to RabbitMQ4

When you run script it automatically detect installation type from $JFROG_HOME/xray/var/etc/installerState.yaml file.

1. Start the Xray service.

   systemd OS

   Bash

   systemctl start xray.service

   systemv OS

   Bash

   systemctl start xray

   Docker Compose

   Bash

   cd jfrog-xray-<version>-compose
   docker-compose -p xray up -d

2. Access Xray from your browser at:

   http://<jfrogUrl>/ui/ , go the Xray tab in the Application module in the UI.

3. Check Xray Log.

   Bash

   tail -f $JFROG_HOME/xray/var/log/console.log

Linux Archive

Starting Xray version 3.131.x, the installer script will allow you to install RabbitMQ 4 and/or Quorum queues, optionally. Before proceeding with the upgrade, make sure your existing Xray deployment is using RabbitMQ version 3.11.x or higher

The installer script provides you with an interactive way to upgrade Xray and its dependencies.

Stage 1

1. Download Xray (Linux Archive).

2. Stop the service.

   Bash

   cd $JFROG_HOME/xray/app/bin
   ./xray.sh stop
   
   or
   
   systemctl stop xray.service

3. Extract the contents of the compressed archive, go to the extracted folder and replace the existing $JFROG_HOME/xray/app with the new app folder.The installer script is located in the extracted folder.

   Bash

   tar -xvf jfrog-xray-<version>-<linux>.tar.gz
   cd jfrog-xray-<version>-<linux>
   
   # Export variables to simplify commands
   export JFROG_HOME=/opt/jfrog
   export JF_NEW_VERSION=/opt/jfrog/jfrog-xray-<version>-linux
   
   # Remove app
   rm -rf $JFROG_HOME/xray/app
   
   # Copy new app
   cp -fr $JF_NEW_VERSION/app $JFROG_HOME/xray/
   
   # Remove extracted new version
   rm -rf $JF_NEW_VERSION

Stage 2

1. Run the installer script.

   If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL), joinKey and the Rabbitmq Quorum queue or version migration.

   Bash

   cd $JFROG_HOME/xray/app/bin
   ./installV2.sh

   

   b. After completing the above, you should wait for the quorum migration to complete. Follow these steps to verify:

   1. Refer Troubleshooting on the Xray-RabbitMQ Quorum Queue migration
   2. Look for these logs in the xray-server.log:

   RabbitMQ migration migrate_msgs_from_other_rabbitmq completed successfully
   RabbitMQ migration delete_classic_queues_vhost completed successfully

   
   

Stage 3

c. The next time you run the same script, it will optionally ask you to upgrade to RabbitMQ4

When you run script it automatically detect installation type from $JFROG_HOME/xray/var/etc/installerState.yaml file.

1. Start the Xray service.

   Bash

   $JFROG_HOME/xray/app/bin/xray.sh start|stop
   
   or
   
   systemctl start xray.service

2. Access Xray from your browser at:

   http://<jfrogUrl>/ui/ , go to the Xray tab in the Application module in the UI.

3. Check Xray Log.

   Bash

   tail -f $JFROG_HOME/xray/var/log/console.log