Xray RabbitMQ Quorum Upgrade

Upgrade an existing JFrog Xray deployment to RabbitMQ Quorum Queues. Choose the section that matches your installer type.

📘

Note

This page covers upgrading an existing Xray instance to RabbitMQ quorum queues. It does not apply to fresh installations. For new deployments, see the fresh installation documentation.

Prerequisites

Before you upgrade to quorum mode:

1. An existing JFrog Xray non-quorum deployment in any of the following modes:

   • Single-node Xray with bundled RabbitMQ
   • Multi-node Xray with bundled RabbitMQ in each node
   • Single-node Xray and Single-node RabbitMQ deployed independently on separate nodes (split mode)
   • Multi-node Xray and Multi-node RabbitMQ deployed independently on separate nodes (split mode)

2. Use Xray version 3.131.x or later. Earlier versions don't support upgrading the bundled RabbitMQ to quorum mode. Always use the latest available version.

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. If not, upgrade to the latest self-managed Xray version first, then proceed with the Quorum Queue migration.

   To check your RabbitMQ version, go to the management UI:

   Text

   http://<any rabbitmq node ip>:15672

   Default credentials are guest / JFXR_RABBITMQ_COOKIE, unless you have overridden them.

4. Ensure indexing queues are empty before starting: no active scans or Watches should be running during the migration.

5. (For linux archive based installs) If you are using a custom Xray user, add the following to /etc/security/limits.conf to set the open file descriptor limit (this is required for RabbitMQ to function properly)

   Text

     <custom user>    soft    nofile    100000
     <custom user>    hard    nofile    100000

6. Ensure all RabbitMQ ports listed in the Xray Network Ports page are open on your nodes. All listed ports are required for correct operation. Additionally, verify that ports 35672–35682 are open, as the quorum migration process includes RabbitMQ CLI checks that depend on these ports.

⚠️

Quorum Queue Node Recommendations (Bundled RabbitMQ)

• Single-node: Supported.
• 3 or more nodes: Supported, but quorum will only grow across the first 3 RabbitMQ nodes. For better stability, splitting RabbitMQ onto dedicated VMs is recommended. See the Split mode architecture for details.
• 2-node deployments: Supported, but not recommended: a 2-node cluster is not fault-tolerant for quorum queues. See the 2-node VM to Quorum migration guide before proceeding.

📘

Note

Migrating to RabbitMQ 4 and 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. Both steps are irreversible once executed and rollback is not supported. Plan your maintenance window accordingly.

The Big Picture

Applies to all installation types: RPM, Debian, Docker Compose, Linux archive

flowchart LR
    subgraph flow[" "]
        direction LR
        S1["Stage 1<br />Stop service<br />Download package"]
        S2["Stage 2<br />Run installer<br />Enable Quorum Queue"]
        V["Verify<br />Quorum migration<br />Wait for completion"]
        S3["Stage 3<br />Re-run installer<br />Upgrade to RabbitMQ 4"]

        S1 --> S2 --> V --> S3
    end

⚠️

Warning

Do not proceed to Stage 3 until verification confirms the quorum migration is complete.

Upgrade Process

Follow the section that matches how your existing Xray instance was installed according to the installer type.

1. Helm

For Helm-based deployments, follow the Quorum Queue Enablement for Xray and Platform Helm Charts guide. It covers both chart types:

1. Xray standalone charts
2. Platform charts

2. Linux Archive/ RPM, DEB / Docker Compose

installv2.sh/configV2.sh (Recommended Installer Script for Version 3.131.x and Later)

Use this script if you run installations manually, or if you previously used install.sh/config.sh and want to move to the supported path. If you're already on installV2.sh/configV2.sh, continue using it for future upgrades.

Follow the guide for your deployment type:

1. Migrate to Quorum using installV2.sh for linux archive
2. Migrate to Quorum using installV2.sh for RPM / DEB
3. Migrate to Quorum using installV2.sh for Docker Compose

❗️

Important

If your existing Xray instance is automated with the original install.sh script, follow the non-breaking upgrade instructions in Upgrade to Quorum Queue via install.sh ( legacy )

The legacy (script install.sh/config.sh) is retained only to avoid breaking existing automated deployments. For all new manual installs, use installV2.sh/configV2.sh.

JFrog Xray Upgrade Guide: RabbitMQ 4.x & Quorum Queues

This section covers common questions and scenarios for upgrading Xray deployments to RabbitMQ 4.x with Quorum Queues enabled.

RabbitMQ 4.x Upgrade Requirement

Upgrading to RabbitMQ 4.x and enabling Quorum Queues is not universally mandatory for all installer types, but is highly recommended.

• Both Helm and non-Helm environments (Docker Compose, RPM, Debian, Linux Archive) will display a warning after the upgrade if still using Classic queues. Customers can retain RabbitMQ 3.x with Classic Queue v1 mirroring, though this introduces severe support, security, and compatibility risks in future versions.

Upgrade Scenarios Matrix

The following matrix summarizes upgrade paths, mandatory status, and behavior by installer type.

Critical Caveats and Risks for Self-Managed Deployments

If a customer chooses the Alternative Mode (upgrading Xray but keeping RabbitMQ 3.x with Classic Queue Mirroring), the support team must clearly communicate the following ramifications:

• 1. Complete Loss of RabbitMQ Support: JFrog will not be able to support or troubleshoot any message broker issues if the customer remains on the deprecated RabbitMQ 3.x version. The customer assumes full operational liability for queue stability.
• 2. Security & Stability Vulnerabilities: RabbitMQ has officially deprecated Classic Queue mirroring in 4.x. Remaining on legacy versions exposes the enterprise environment to unpatched security vulnerabilities and known performance degradation.
• 3. Next-Gen OS Incompatibility: Modern operating systems such as RHEL 10 and Debian 13 completely drop support for RabbitMQ 3.x due to underlying Erlang version compatibility limitations. Upgrading the underlying host OS will break the Xray deployment.
• 4. Migration is One-Way (Irreversible): When customers use installV2.sh or configV2.sh to migrate to Quorum queues, the process is completely irreversible. There is no supported path to rollback to Classic Queues. Ensure full backups of ${JF_PRODUCT_HOME}/var/data/rabbitmq are taken before proceeding.

Related Topics

• Xray Upgrade
• Upgrade to Quorum Queue via install.sh (legacy)
• Quorum Queue Enablement for Xray and Platform Helm Charts
• RabbitMQ HA in Xray Using Quorum Queues
• RabbitMQ Split for Xray