Upgrading Xray

Overview

The procedure to upgrade Xray depends on your installation type. We strongly recommend reading through this page before proceeding with your upgrade.

Before you upgrade Xray please refer to additional information on system requirements (for storage, databases, browsers and other requirements), and the system architecture.

There are several new concepts introduced in Xray 3.x, improving the installation and customization process.

Note: Make sure to use the same upgrade method (RPM, Debian, Docker, etc.) as the one you initially used to install Xray.

Xray supports high availability (HA) and hot upgrade of HA installations from version 3.31.0. For more information on HA upgrade, see HA Upgrade.

Upgrading to version 3.x for the first time?

Remember that when using the PostgreSQL command below to only use the version you running.

It is recommended that you first review what's new with the latest JFrog Platform. Review the breaking changes, deprecated features and more.

Before You Proceed

To ensure you can restore your Xray and database in case you encounter any issues during the upgrade process, we strongly recommend you make sure your system and database backups are up to date.

From version 3.x, MongoDB will not be used by Xray except during the initial migration phase from version 2.x. The data will be automatically migrated from MongoDB to PostgreSQL. Make sure your PostgreSQL storage size is increased by at least 2.5 times than its current size.

Do you have more than one Artifactory instance connect to your single Xray instance?

When upgrading to the JFrog Platform, Xray must be connected only to a single Artifactory instance. If you have one Xray instance connected to more than one Artifactory instances, use one of the following options before proceeding with any upgrade:

Option 1 (recommended): Keep one connected Artifactory instance to your single Xray instance, and upgrade the rest to version 7.x with newly installed Xray version 3.x instances. This option will require re-indexing the the additional Artifactory instances, and will cause some loss of configuration data. Learn More >

Option 2: Install additional Xray version 2.x instances for each Artifactory instance that you have, and restore all MongoDB and PostgreSQL data. Continue to upgrade each Artifactory and Xray pairs to version 7.x and version 3.x. This procedure is only suggested if you must keep all your Xray configurations and easily reconfigure them in the new instances. Learn More >

Upgrading the Xray PostgreSQL

Xray 3.x and 2.x support PostgreSQL versions 9.5, 9.6, 10, 11, 12 (the earliest version of Xray 2.x that supports PostgreSQL 10-12 is Xray 2.16). Because PostgreSQL is ending its support for some of its older versions, including 9.5 in February 2021 and 9.6 in November 2021. Although it is possible to upgrade incrementally from 9.5 to 9.6, JFrog recommends upgrading to PostgreSQL 13. This will extend the time until the next PostgreSQL end of support and enables Xray to take advantage of the latest abilities provided by the new versions, such as better performance, etc

To learn about the process and requirements for upgrading PostgreSQL, see JFrog Xray PostgreSQL Upgrade - PostgreSQL 9.x EoS.

Upgrade Steps

The upgrade procedure involves the following steps:

Download Xray (Docker Compose, RPM, Debian).
Stop the Xray service
Install Xray according to the distribution type.
Check the Migration Log and review system.yaml to validate the migration was successful (only for upgrading from v3.x).
Start the service using the start scripts or OS service management.
Check the Xray Log for the status of the service.

Default Home Directory / $JFROG_HOME

The default Xray home directory is defined according to the installation type. For additional details see the Product Directory Structure page.

Note: This guide uses $JFROG_HOME to represent the JFrog root directory containing the deployed product.

JFrog Subscription Levels

SELF-HOSTED

_{PRO X
ENTERPRISE
ENTERPRISE+}

Page Contents

Upgrading from Version Below 2.7

To upgrade from version 2.6 and below, you first need to upgrade to version 2.7.x as described in the Upgrading Xray 2 documentation, and then continue to upgrade from version 2.7 to 3.x.

From version 3.x, the MongoDB is not used by Xray, except during the initial migration phase from version 2.x. The data is automatically migrated from MongoDB to PostgreSQL from version 2.7x and above. After upgrading to version 2.7x, you must ensure that all data migrations are complete before proceeding to upgrade to version 3.x. The xray-migration-readiness tool enables you to verify that all data migrations are complete. Download the tool, and follow the instructions in the readme file.

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

Upgrading from Version 2.7 to 3.x

JFrog Xray v3.x is only compatible with JFrog Artifactory v7.x. To upgrade, you must first install JFrog Artifactory 7.x.

The following upgrade methods are supported:

Interactive Script (RPM, Debian and Docker Compose)
Manual RPM
Manual Debian

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

Migrating data from MongoDB to PostgreSQL

From version 3.x, Xray does not use MongoDB except during the migration phase. On start of version 3.x, data is automatically migrated from MongoDB to PostgreSQL. Make sure both the databases are up and running before Xray services are started. During the migration, Xray will not be accessible. The migration duration depends on the data size to be migrated.

Interactive Script Upgrade (recommended)

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.

Download Xray (RPM, Debian or Docker Compose).

Stop the service.

Docker - Stop and remove xray containers

xray stop
docker ps -a --format '{{.Names}}' | grep ^xray_* | xargs docker rm -f

RPM/DEB

cd /opt/jfrog/xray/scripts
./xray.sh stop

Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.
```
tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-xray-<version>-<compose|rpm|deb>
```
.env file included within the Docker-Compose archive

This .env file is used by docker-compose and is updated during installations and upgrades.
Notice that some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.
For non Docker-Compose installations, make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.
For Docker-Compose installations, MongoDB services will come up as part of the new compose files.
Run the installer script.
Note: the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Compose
```
./config.sh
```
.env in Docker-Compose

A .env file is included within the archive. This file is used by docker-compose and is updated during installations and upgrades.
Some Operating Systems do not display dot files by default so please be aware of this file.
If you make changes to the file, remember to backup before an upgrade
RPM/DEB
```
./install.sh
```
Check that the configurations migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/xray/var/log/migration.log file
2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.
  
  Please ensure that a large file handle limit is specified before you start Xray.

Start the Xray service.

systemd OS

systemctl start xray.service

Starting from Xray 3.8x the stop and restart action on Xray will not be applied to RabbitMQ process. On start action of Xray, if RabbitMQ is not running , it will be started.

If you want the script to perform stop and restart action on RabbitMQ, set shared.rabbitMq.autoStop as true in the system.yaml. Note that this flag is not consumed in docker-compose installation.

systemv OS

systemctl start xray

Docker Compose

cd jfrog-xray-<version>-compose

# Starting from Xray 3.8x RabbitMQ has been moved to a compose file of its own, this needs to be started before starting other services
docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d

# Starting from Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
docker-compose -p xray-postgres -f docker-compose-postgres-9-5-2v.yaml up -d

docker-compose -p xray up -d

docker-compose -p xray ps
docker-compose -p xray down

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.
Check Xray Log.
Linux
```
tail -f $JFROG_HOME/var/log/console.log
```

Post Data Migration Steps (MongoDB to PostgreSQL)

After the migration is successfully ended, it is recommended to complete the following steps:

Validate that your Xray data has migrated successfully.
Remove MongoDB configuration from the system.yaml.
For RPM installations, uninstall the MongoDB database.
For Docker-Compose installations, you either need to remove the "mongodb" service from the docker-compose.yml files, or run the installation script again, the script will determine that MongoDB is no longer necessary and will do this automatically.

Manual RPM Upgrade

The RPM upgrade bundles Xray and all its dependencies. It is provided as native RPM packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

Download Xray (RPM).

Stop the current service.

cd /opt/jfrog/xray/scripts
./xray.sh stop

Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-xray-<version>-rpm.tar.gz
cd jfrog-xray-<version>-rpm
```
Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.
Install Xray as a service on Red Hat compatible Linux distributions, as a root user.
```
yum -y install ./xray/xray.rpm
```
Check that the migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/xray/var/log/migration.log file
2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.
  
  Please ensure that a large file handle limit is specified before you start Xray.
Set the Artifactory connection details.
Xray requires a working Artifactory server and a suitable license. The Xray connection to Artifactory requires 2 parameters:
- jfrogUrl - URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. It is recommended to use DNS names rather than direct IPs. For example: "http://jfrog.acme.com or http://10.20.30.40:8082". Note that /artifactory context is not longer required.
  Set it in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.
- join.key - This is the "secret" key required by Artifactory for registering and authenticating the Xray server.
  You can fetch the Artifactory joinKey (join Key) from the JPD UI in the User Management | Settings | Join Key.
  Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.
Make sure the third party services are running.
PostgreSQL
If you had the PostgreSQL database that was packaged as part of 2.x installed, the same will be used in the current installation. It can be managed using the following commands:
service postgresql-9.5 start|stop|status
RabbitMQ
From version 3.x, RabbitMQ is packaged and managed as part of the Xray RPM. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well. The existing RabbitMQ RPM which was installed as part of 2.x can be uninstalled after Xray 3.x is successfully installed and running.
Migrating data from MongoDB to PostgreSQL
From version 3.x, Xray will not use MongoDB except during the migration phase. Make sure both the databases are up and running before Xray services are started. During the migration, Xray will not be accessible. You can uninstall MongoDB after Xray 3.x is successfully installed and running.
service mongod start|stop|status

Start Xray.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Post Data Migration Steps (MongoDB to PostgreSQL)

After the migration is successfully ended, it is recommended to complete the following steps:

Validate that your Xray data has migrated successfully.
Remove MongoDB configuration from the system.yaml.
Uninstall the MongoDB database.

Manual Debian Upgrade

The Debian upgrade bundles Xray and all its dependencies. It is provided as native Debian packages, where Xray and its dependencies must be installed separately. Use this, if you are automating installations.

Download Xray (Debian).

Stop the current server.

cd /opt/jfrog/xray/scripts
./xray.sh stop

Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-xray-<version>-deb.tar.gz
cd jfrog-xray-<version>-deb
```
Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL works.
Install Xray as a service on a Debian compatible Linux distributions, as a root user.
Run Installation
```
dpkg -i ./xray/xray.deb
```
Check that the migration has completed successfully, by reviewing the following files:
1. migration log: $JFROG_HOME/xray/var/log/migration.log file
2. system.yaml configuration: $JFROG_HOME/xray/var/etc/system.yaml
  This newly created file will contain your current custom configurations in the new format.
  
  Please ensure that a large file handle limit is specified before you start Xray.
Set the Artifactory connection details.
Xray requires a working Artifactory server and a suitable license. The Xray connection to Artifactory requires 2 parameters:
- jfrogUrl - URL to the machine where JFrog Artifactory is deployed, or the load balancer pointing to it. It is recommended to use DNS names rather than direct IPs. For example: "http://jfrog.acme.com or http://10.20.30.40:8082". Note that /artifactory context is not longer required.
  Set it in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.
- join.key - This is the "secret" key required by Artifactory for registering and authenticating the Xray server.
  You can fetch the Artifactory joinKey (join Key) from the JPD UI in the User Management | Settings | Join Key.
  Set the join.key used by your Artifactory server in the Shared Configurations section of the $JFROG_HOME/xray/var/etc/system.yaml file.
Make sure the third party services are running.
PostgreSQL
If you had the PostgreSQL database that was packaged as part of 2.x installed, the same will be used in the current installation. It can be managed using the following commands:
service postgresql-9.5 start|stop|status
RabbitMq
From 3.x, RabbitMQ is packaged and managed as part of the Xray DEB. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well. The existing RabbitMQ DEB which was installed as part of 2.x can be uninstalled after Xray 3.x is successfully installed and running.
MongoDB
From 3.x, Xray will not use MongoDB except during migration. On start of 3.x, data will be migrated from MongoDB to PostgreSQL. Make sure both the databases are up and running before Xray services are started. You can uninstall MongoDB after Xray 3.x is successfully installed and running.
service mongod start|stop|status

Start Xray.

systemd OS

systemctl start xray.service

Systemv OS

systemctl start xray

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Post Data Migration Steps (MongoDB to PostgreSQL)

After the migration is successfully ended, it is recommended to complete the following steps:

Validate that your Xray data has migrated successfully.
Remove MongoDB configuration from the system.yaml.
Uninstall the MongoDB database.

HA Upgrade

This section describes the process to upgrade your Xray High Availability cluster.

Upgrading an Xray 2.x HA Cluster

The Xray load balancer is no longer required when upgrading an Xray HA cluster from version 2.x to 3.x as all the Xray requests are now routed through the Platform Router in the JFrog Platform.

The following installation methods are supported:

Docker Compose
RPM / Debian

Before you upgrade, ensure that the operating system version that you use is supported. See System Requirements for detailed information on operating system support.

Docker Compose

Perform the following steps for each node in your system. When starting up each node, make sure to enter the correct details according to first node or additional node being added to the cluster.

The instructions below assume that you are upgrading from a 2.X official Docker installation.

Stop all the cluster nodes that are setup using HA by running the following command on each node.
```
./xray stop all
```
Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-xray-<version>-compose.tar.gz
cd jfrog-xray-<version>-compose.tar.gz
```
.env file included within the Docker-Compose archive

This .env file is used by docker-compose and is updated during installations and upgrades.
Notice that some operating systems do not display dot files by default. If you make any changes to the file, remember to backup before an upgrade.
Run the config.sh script to setup folders with required ownership. Note: the script will prompt you with a series of mandatory inputs, including if this is part of a cluster, and configure the needed system.yaml.
```
./config.sh
```
Note: For the first node upgrade, make sure to select "N" when prompted if you are adding an additional node to an existing product cluster. For the following additional nodes, make sure to select "Y" and provide the Join Key and JFrog URL.

Start the node.

Run this command only from the extracted folder.

Manage Xray using docker-compose commands.

cd jfrog-xray-<version>-compose

# Starting from Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
if PostgreSQL 9.5.2 running use -   docker-compose -p xray-postgres -f docker-compose-postgres-9-5-2v.yaml up -d
if PostgreSQL 10.13  running use -   docker-compose -p xray-postgres -f docker-compose-postgres-10-13v.yaml up -d
if PostgreSQL 12.3   running use -   docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d

docker-compose -p xray up -d

docker-compose -p xray ps
docker-compose -p xray down

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.
```
docker-compose -p xray logs
```
Check Xray Log.

RPM/Debian

Upgrading the First Node

Stop all the cluster nodes that are setup using HA by running the following command on each node.
```
service xray stop
```
Make sure your MongoDB and PostgreSQL are running in the background.
Extract the contents of the compressed archive and go to the extracted folder.
RPM
```
tar -xvf jfrog-xray-<version>-rpm.tar.gz
```
Debian
```
tar -xvf jfrog-xray-<version>deb.tar.gz
```
Run the install.sh script to setup folders with required ownership.
```
./install.sh
```
Add the following to the $<PostgreSQL home folder>/data/pg_hba.conf file.
```
host    all             all             0.0.0.0/0               md5
```
Add the following to the $<PostgreSQL home folder>/data/postgresql.conf file.
```
listen_addresses='*'
```
Restart PostgreSQL.
```
service postgresql-<version> stop
service postgresql-<version> start
```
From Xray version 3.x, RabbitMQ is packaged and managed as part of the Xray RPM. Any action (stop, start and status) on the main service of Xray will be performed on RabbitMQ as well.
The existing RabbitMQ RPM which was installed as part of Xray version 2.x can be uninstalled after Xray 3.x is successfully installed and running.

Start the Xray node.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Manage Xray using the following commands.

systemd OS

systemctl stop xray.service

systemv OS

service xray stop|status|restart

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Upgrading the additional Node

Stop all the cluster nodes that are setup using HA by running the following command on each node.
```
service xray stop
```
Extract the contents of the compressed archive and go to the extracted folder.
RPM
```
tar -xvf jfrog-xray-<version>-rpm.tar.gz
```
Debian
```
tar -xvf jfrog-xray-<version>-deb.tar.gz
```
Run the config.sh script to setup folders with required ownership.
```
./install.sh
```

Modify the system.yaml file located in the $JFROG_HOME/xray/var/etc folder with the following configurations.

shared:
   rabbitMq:
      active:
         node:
            name: <node-name> (use same name across all subsequent nodes)
            ip: <first-node-ip>

Start the Xray node.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Manage Xray using the following commands.

systemd OS

systemctl stop xray.service

systemv OS

service xray stop|status|restart

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Post Data Migration Steps (MongoDB to PostgreSQL)

After the migration is successfully ended, it is recommended to complete the following steps:

Validate that your Xray data has migrated successfully.
Remove MongoDB configuration from the system.yaml.
Uninstall the MongoDB database.

Upgrading from Version 3.x to 3.x

The following upgrade methods are supported:

Interactive Script (Recommended)
Manual RPM / Debian
Linux Archive
Helm

Interactive Script Upgrade (Recommended)

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.

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

Stop the service.

systemd OS

systemctl stop xray.service

systemv OS

service xray stop

Docker Compose

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

Extract the contents of the compressed archive and go to the extracted folder. The installer script is located in the extracted folder.
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.
```
tar -xvf jfrog-xray-<version>-<compose|rpm|deb>.tar.gz
cd jfrog-xray-<version>-<compose|rpm|deb>
```
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.
Run the installer script.
If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Compose
```
./config.sh
```
RPM/DEB
```
./install.sh
```

Start the Xray service.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Docker Compose

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

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Manual RPM/Debian Upgrade

Download Xray (RPM or Debian)

Stop the current server.

systemd OS

systemctl stop xray.service

systemv OS

service xray stop

Store the RabbitMQ password securely before you proceed with the upgrade.
You can find the password inside the file, $JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf.
Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-xray-<version>-<rpm|deb>.tar.gz
cd jfrog-xray-<version>-<rpm|deb>
```
Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and it requires an upgrade of the Erlang library. This library can be found on $JFROG_HOME/xray/app/third-party. For more information, see Installing Erlang.

To upgrade the dependencies for RabbitMQ, you will need to upgrade socat/erlang by using "--replacefiles" to work around a file conflict error.
Install Xray as a service on Red Hat compatible Linux distributions, as a root user.
rpm
```
yum -y install ./xray/xray.rpm
```
Debian
```
dpkg -i ./xray/xray.deb
```
Update the RabbitMQ password inside the file, $JFROG_HOME/app/bin/rabbitmq/rabbitmq.conf, with the password that you previously stored.

Start Xray.

systemd OS

systemctl start xray.service

systemv OS

systemctl start xray

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Xray tab in the Application module in the UI.

Check Xray Log.

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

Manual Docker Compose Upgrade

Stop the current server.
```
docker-compose -p xray down
```
Extract the contents of the compressed archive and go to the extracted folder.
```
tar -xvf jfrog-xray-<version>-compose.tar.gz
```
.env file included within the Docker-Compose archive

This .env file is used by docker-compose and is updated during installations and upgrades.
Notice that some operating systems do not display dot files by default. If you've made any changes to the file, remember to backup before an upgrade.
Copy the docker-compose template from the templates folder to the extracted folder. Rename it as docker-compose.yaml. Ensure that you use the same template as you did during the installation.
Requirement Template
Xray docker-compose.yaml
RabbitMQ docker-compose-rabbitmq.yaml
PostgreSQL
docker-compose-postgres.yaml
Docker for Mac
When you use Docker Compose in Mac, /etc/localtime might not work as expected since it might not be a shared location in the docker-for-mac settings.
You can remove the following line from the selected docker-compose.yaml file to avoid installation issues.
- /etc/localtime:/etc/localtime:ro

Update the .env file and ensure that you use the same values when you did the installation.

## The Installation directory for Xray. If not entered, the script will prompt you for this input. Default [$HOME/.jfrog/xray]
ROOT_DATA_DIR=

# Host ID. Other nodes in the cluster will use this ID to identify this node
HOST_ID=

# ID of the active node. Please leave the value as "None" for active nodes. (shared.rabbitMq.active.node.name).  
JF_SHARED_RABBITMQ_ACTIVE_NODE_NAME=None 

# IP of the active node. (shared.rabbitMq.active.node.ip)
JF_SHARED_RABBITMQ_ACTIVE_NODE_IP=127.0.0.1

# Bind IP for Internal ports of Third party applications
JF_THIRD_PARTY_BIND_IP=127.0.0.1

Start Xray and PostgreSQL using docker-compose commands.

## RabbitMQ needs to be started before starting other services
docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml up -d
  
## From Xray 3.8.x, PostgreSQL needs to be started before starting the other services.
docker-compose -p xray-postgres -f docker-compose-postgres.yaml up -d
 
docker-compose -p xray up -d
 
## Check whether service is up
docker-compose -p xray ps

Access Artifactory from your browser at: http://SERVER_HOSTNAME/ui/. For example, on your local machine: http://localhost/ui/.
Check Xray log.
```
docker ps
docker-compose -p xray logs
```
Configuring the Log Rotation of the Console Log

The console.log file can grow quickly since all services write to it. The installation scripts add a cron job to log rotate the console.log file every hour.
This is not done for manual Docker Compose installations. Learn more on how to configure the log rotation.

Linux Archive Upgrade

Remember to back up the RabbitMQ password and to add it back to the rabbitmq.conf file.

Stop the current server.

Stop Xray

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

Extract the contents of the compressed archive and go to the extracted folder.
Untar
```
mv jfrog-xray-<version>-linux.tar.gz /opt/jfrog/
cd /opt/jfrog
tar -xf jfrog-xray-<version>-linux.tar.gz
```
Starting from Xray 3.8.x, RabbitMQ bundled with Xray has been upgraded, and it requires an upgrade of the Erlang library. This library can be found on $JFROG_HOME/xray/app/third-party. For more information, see Installing Erlang.

Replace the existing $JFROG_HOME/xray/app with the new app folder.

Upgrade

# 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

Manage Xray.

$JFROG_HOME/xray/app/bin/xray.sh start|stop

Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Dashboard tab in the Application module in the UI.

Check Xray Log.

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

Helm Upgrade

When upgrading from Xray chart version 3.x to 3.x, due to breaking changes, use kubectl delete statefulsets <old_statefulset_xray_name> and run the helm upgrade.

Also, While upgrading from Xray chart version 3.x to 4.x, due to breaking RabbitMQ (whenrabbitmq.enabled=true) subchart changes, run the following commands.

$ kubectl delete statefulsets <old_statefulset_xray_name>
$ kubectl delete statefulsets <old_statefulset_rabbitmq_name>
$ kubectl delete pvc <old_PVC_rabbitmq_name>
$ helm upgrade --install xray --namespace xray jfrog/xray

Downtime is required to perform an upgrade.

Offline Update

If you wish to do an offline update of the Xray database while running in pods, copy the downloaded data into the correct Xray container (scale down to 1 replica if needed before) and then using kubectl commands copy the file to the specific location.

For example:

kubectl cp ./comp_-6795364578871.zip <namespace>/xray-0:/opt/jfrog/xray/var/work/server/updates/component/comp_-6795364578871.zip -c xray-server
kubectl cp ./vuln_-6795364578871.zip <namespace>/xray-0:/opt/jfrog/xray/var/work/server/updates/vulnerability/vuln_-6795364578871.zip -c xray-server

To upgrade Xray.

Update the existing deployed version to the updated version.

helm repo update

helm upgrade --install <myrelease> --namespace xray jfrog/xray

If Xray was installed without providing a value to postgresql.postgresqlPassword (the password was autogenerated), follow these instructions.
1. Get the current password by running the following.
```
POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)
```
2. Upgrade the release by passing the previously auto-generated secret.
```
helm upgrade <myrelease> jfrog/xray --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}
```
If Xray was installed without providing a value to rabbitmq.auth.password (the password was autogenerated), follow these instructions.
1. Get the current password by running the following.
```
RABBITMQ_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-rabbitmq -o jsonpath="{.data.rabbitmq-password}" | base64 --decode)
```
2. Upgrade the release by passing the previously auto-generated secret.
```
helm upgrade <myrelease> jfrog/xray --set rabbitmq.auth.password=${RABBITMQ_PASSWORD}
```
If Xray was installed with all of the default values (e.g., with no user-provided values for Rabbit/Postgres), follow these steps.
1. Retrieve all current passwords (RabbitMQ/PostgreSQL) as explained in the above section.
2. Upgrade the release by passing the previously auto-generated secrets.
```
helm upgrade --install xray --namespace xray jfrog/xray --set rabbitmq.auth.password=<rabbit-password> --set postgresql.post
```
Access Xray from your browser at: http://<jfrogUrl>/ui/, then go to the Xray tab in the Application module in the UI.
Check the status of your deployed helm releases.
```
helm status xray
```

Upgrading the Chart Versions from 1.x/2.x to 3.x and Above

JFrog Xray 3.x is only compatible with JFrog Artifactory 7.x; to upgrade, you must first install JFrog Artifactory 7.x.
To upgrade from a version prior to 1.x, you will first need to upgrade to the latest version of 1.x
To upgrade from a version of 2.x, you first need to upgrade to the latest version of 2.x (for more information, see Upgrading Xray 2 documentation).

PostgreSQL Migration Process

The recommended migration process has two main steps:

Migrate the existing MongoDB data to an existing PostgreSQL.
Perform a full database export and import of PostgreSQL.

Prerequisite Step: Get the Details of the Existing Chart

Block user access to Xray (but do not shut down).

Get the service names OLD_PG_SERVICE_NAME, OLD_MONGO_SERVICE_NAME using the command below. For example: OLD_PG_SERVICE_NAME and OLD_MONGO_SERVICE_NAME values as <OLD_RELEASE_NAME>-postgresql and <OLD_RELEASE_NAME>-mongodb respectively.

$ kubectl get svc
NAME                                       TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)                       AGE
<OLD_RELEASE_NAME>-mongodb                 ClusterIP      10.101.56.69     <none>        27017/TCP                     114m
<OLD_RELEASE_NAME>-postgresql              ClusterIP      10.101.250.74    <none>        5432/TCP                      114m
<OLD_RELEASE_NAME>-rabbitmq-ha             ClusterIP      None             <none>        15672/TCP,5672/TCP,4369/TCP   114m
<OLD_RELEASE_NAME>-rabbitmq-ha-discovery   ClusterIP      None             <none>        15672/TCP,5672/TCP,4369/TCP   114m
<OLD_RELEASE_NAME>-xray-analysis           ClusterIP      10.104.138.63    <none>        7000/TCP                      114m
<OLD_RELEASE_NAME>-xray-indexer            ClusterIP      10.106.72.163    <none>        7002/TCP                      114m
<OLD_RELEASE_NAME>-xray-persist            ClusterIP      10.103.20.33     <none>        7003/TCP                      114m
<OLD_RELEASE_NAME>-xray-server             LoadBalancer   10.105.121.175   <pending>     80:32326/TCP                  114m

Save the previous passwords OLD_PG_SERVICE_NAME, OLD_MONGO_SERVICE_NAME or extract them from the secret of the existing PostgreSQL and MongoDB pods.

#Example:
OLD_PG_PASSWORD=$(kubectl get secret -n <namespace> <OLD_RELEASE_NAME>-postgresql -o jsonpath="{.data.postgres-password}" | base64 --decode)
OLD_MONGO_PASSWORD=$(kubectl get secret -n <namespace> <OLD_RELEASE_NAME>-mongodb -o jsonpath="{.data.mongodb-password}" | base64 --decode)

Stop the old Xray pods (scale down replicas to 0). The PostgreSQL and MongoDB pods will still remain active.

$ kubectl scale statefulsets <REPLACE_OLD_RELEASE_NAME>-rabbitmq-ha <REPLACE_OLD_RELEASE_NAME>-xray-analysis <REPLACE_OLD_RELEASE_NAME>-xray-indexer <REPLACE_OLD_RELEASE_NAME>-xray-persist <REPLACE_OLD_RELEASE_NAME>-xray-server --replicas=0

Migrate the Existing MongoDB Data to an Existing PostgreSQL

Run the helm install (not upgrade) with the new version say xray-new in the following way.

Verify that all probes are disabled.

--set router.livenessProbe.enabled=false --set router.readinessProbe.enabled=false --set indexer.livenessProbe.enabled=false --set analysis.livenessProbe.enabled=false --set server.livenessProbe.enabled=false --set persist.livenessProbe.enabled=false --set indexer.readinessProbe.enabled=false --set analysis.readinessProbe.enabled=false --set server.readinessProbe.enabled=false --set persist.readinessProbe.enabled=false

Point to the previous PostgreSQL pod (user, password,DATABASE).

--set postgresql.enabled=false --set database.user=<OLD_PG_USERNAME> --set database.password=<OLD_PG_PASSWORD> --set database.url="postgres://<SERVICE_NAME_POSTGRES>:5432/xraydb?sslmode=disable"

Point to the previous MongoDB (user, password,DATABASE) pod.

--set xray.mongoUsername=<OLD_MONGO_USERNAME> --set xray.mongoPassword=<OLD_MONGO_PASSWORD> --set xray.mongoUrl="mongodb://<SERVICE_NAME_MONGODB>:27017/?authSource=xray&authMechanism=SCRAM-SHA-1"

This will trigger the migration process as per the example below.

# Create a customvalues.yaml file

router: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
indexer: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
analysis: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
server: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false  
persist: 
  livenessProbe:
    enabled: false
  readinessProbe: 
    enabled: false
postgresql:
  enabled: false
database: 
  user: <OLD_PG_USERNAME>
  password: <OLD_PG_PASSWORD>
  url: "postgres://<SERVICE_NAME_POSTGRES>:5432/xraydb?sslmode=disable"
xray: 
  mongoUsername: <OLD_MONGO_USERNAME>
  mongoPassword: <OLD_MONGO_PASSWORD>
  mongoUrl: "mongodb://<SERVICE_NAME_MONGODB>:27017/?authSource=xray&authMechanism=SCRAM-SHA-1"
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
rabbitmq:
  enabled: true
  auth: 
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false

Apply the values.yaml file during installation.

helm upgrade --install xray-new jfrog/xray -f customvalues.yaml

Stop the new Xray pods (scale down replicas to 0). Both PostgreSQL pods still remain active.

Create a customvalues.yaml file.

replicaCount: 0
postgresql:
  postgresqlPassword: <NEW_PG_PASSWORD>
rabbitmq:
  enabled: true
  auth:
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false
xray: 
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
unifiedUpgradeAllowed: true
databaseUpgradeReady: true

Apply the values.yaml file during installation.

helm upgrade --install xray-new jfrog/xray -f customvalues.yaml

Perform a Full Database Export and Import of PostgreSQL

To migrate PostgreSQL data between old and new pods.

Connect to the new PostgreSQL pod (you can obtain the name by running kubectl get pods).
```
$ kubectl exec -it <NAME> bash
```
Once logged in, create a dump file from the previous database using pg_dump, and connect to the previous PostgreSQL chart.
```
$ pg_dump -h <OLD_PG_SERVICE_NAME> -U xray DATABASE_NAME > /tmp/backup.sql
```
After running this command, you will be prompted for a password; this password is the previous chart password OLD_PG_PASSWORD. This operation could take some time depending on the database size.
Once you have the backup file, you can restore it with this command.
```
$ psql -U xray DATABASE_NAME < /tmp/backup.sql
```
After running the command above, you will be prompted for a password; this is the current chart password. This operation could take some time depending on the database size.

Next, run the upgrade command one final time to start Xray.

# Create a customvalues.yaml file
xray: 
  masterKey: <PREVIOUS_MASTER_KEY>
  jfrogUrl: <NEW_ARTIFACTORY_URL>
  joinKey: <JOIN_KEY>
rabbitmq:
  enabled: true
  auth: 
    password: <PASSWORD>
rabbitmq-ha:
  enabled: false
postgresql:
  postgresqlPassword: <NEW_PG_PASSWORD>
unifiedUpgradeAllowed: true
databaseUpgradeReady: true

Apply the values file during the installation.

helm upgrade --install xray-new jfrog/xray -f customvalues.yaml

Restore access to the new Xray by running the command below to remove the old Xray deployment and Helm release.
```
run helm delete <OLD_RELEASE_NAME>
```

Xray should now be ready for use.

RabbitMQ Migration Process

The RabbitMQ-HA chart has been removed from the 7.x chart versions; therefore, before upgrading to the 7.x chart versions, you will need to perform the RabbitMQ migration (assuming you are not using the Bitnami RabbitMQ). This section describes the steps for migrating from the RabbitMQ-HA chart to the Bitnami RabbitMQ chart before upgrading to chart version 7.x and above.

For this procedure, you will need to choose whether to migrate without existing queues (assuming that all queues are empty) or to migrate while Xray is down.

Migrating without Existing Queues

Important

This procedure assumes that all queues are empty.

While running the helm upgrade, make sure that there are no indexing or Watches running.

Upgrade Xray with Bitnami RabbitMQ (disabling RabbitMQ-HA).

yaml
     rabbitmq-ha:
       enabled: false
     rabbitmq:
       enabled: true
       auth:
         username: guest
         password: password

Migrating with Existing Queues

This migration option, which requires downtime, is intended for situations where there are unfinished tasks running in Xray, but the migration to Bitnami RabbitMQ is necessary.

Detach (disable) Xray in Artifactory.
Upgrade Xray with both RabbitMQs (RabbitMQ-HA and Bitnami RabbitMQ) and scale down the Xray services to 0 (replicaCount: 0).

Both RabbitMQs should be scaled down to one replica. Both RabbitMQs should have the ha-mode: all set (by default they should already be set).
```
yaml
     xray:
     replicaCount: 0
     rabbitmq-ha:
       enabled: true
       replicaCount: 1
     rabbitmq:
       enabled: true
       replicaCount: 1
       auth:
         username: guest
         password: guest
```

Go into the Bitnami RabbitMQ pod and run the following.

bash
    export OLD_RMQ=rabbit@`<RELEASE_NAME>`-rabbitmq-ha-0.`<RELEASE_NAME>`-rabbitmq-ha-discovery.`<NAMESPACE_NAME>`.svc.cluster.local && \
    rabbitmqctl stop_app && \
    rabbitmqctl join_cluster $OLD_RMQ && \
    rabbitmqctl start_app

The process of data synchronization between RabbitMQ -HA and the new Bitnami RabbitMQ node begins.

Verify the synchronization with the queue size and count using the command rabbitmqctl list_queues. The synchronization status can also be viewed from the RabbitMQ dashboard of the old RabbitMQ (RabbitMQ-HA).

When all the data has been synchronized between the cluster nodes, run a helm upgrade to disable the RabbitMQ-HA. This removes the old RabbitMQ-HA and brings up the Xray services.

yaml
     xray:
     replicaCount: 1
     rabbitmq-ha:
       enabled: false
     rabbitmq:
       enabled: true
       replicaCount: 1
       auth:
         username: guest
         password: guest

Finally, remove the old node from the Bitnami RabbitMQ.

bash
     rabbitmqctl forget_cluster_node rabbit@`<RELEASE_NAME>`-rabbitmq-ha-0.`<RELEASE_NAME>`-rabbitmq-ha-discovery.`<NAMESPACE_NAME>`.svc.cluster.local

Enable Xray in Artifactory.

HA Upgrade

This section describes the process of upgrading your Xray High Availability cluster using the interactive script.

The upgrade supports the following installation types:

Linux Archive
Docker Compose
RPM/Debian

Starting from version 3.31.0 and later, Xray supports hot upgrade for HA installations. Unlike regular upgrades, you need not turn off the secondary nodes while upgrading a node.

To perform a hot upgrade, ensure that all the nodes in the HA cluster run on the same version. For example, you cannot perform hot upgrade if one node is in version 3.31.0 and the two other nodes are in 3.31.1. While the upgrade is in process, you cannot do a DB sync. You must not restart any node while hot upgrade is in process. If you restart a node in the middle of the process, the node will not be able to rejoin the cluster. The JFrog Platform UI displays a warning message while the upgrade is in process. You cannot downgrade to a previous version using the hot upgrade process

Since Xray supports hot upgrade from version 3.31.0, you can perform hot upgrade to upgrade the HA installation in 3.31.0 to a version higher than 3.31.0.

Upgrade from Versions Higher than 3.31.0

Follow these steps to upgrade Xray using the interactive script on each node in the cluster.

Stop the Xray service on the node that you want to upgrade.
Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh stop
```
Docker Compose
```
docker-compose -p xray down
```
RPM/Debian
```
systemctl stop xray
```
For Linux Archive only: Delete the app folder.
Upgrade Xray by running the installer script.
If needed, the script prompts you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
./install.sh
```

Start the Xray services.

Linux Archive

$JFROG_HOME/xray/app/bin/xray.sh start

Docker Compose

docker-compose -p xray up -d

RPM/Debian

systemctl start xray

Upgrade from Versions Prior to 3.31.0

Follow these steps to upgrade Xray using the interactive script.

Linux and Native Installers

Before running the upgrade on Linux and Native installers, you will need to stop RabbitMQ. Because shared.rabbitMq.autoStop is set to false by default. to be able to run RabbitMQ with systemctl/xray.sh, you will need to set shared.rabbitMq.autoStop to true.in the system.yaml .

Docker Compose

For Docker Compose, you will need to run the

docker-compose -p xray-rabbitmq -f docker-compose-rabbitmq.yaml down

Stop the Xray services on all secondary nodes.
Important

You must stop the services on the secondary nodes before stopping the services on the master node.
Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh stop
```
Docker Compose
```
docker-compose -p xray down
```
RPM/Debian
```
systemctl stop xray
```
Next, stop the Xray services on the master node.
Linux Archive
```
$JFROG_HOME/xray/app/bin/xray.sh stop
```
Docker Compose
```
docker-compose -p xray down
```
RPM/Debian
```
systemctl stop xray
```
For Linux Archive only: Delete the app folder on all nodes (master and secondary).
Upgrade Xray on the master node by running the installer script.
If needed, the script will prompt you with a series of mandatory inputs, including the jfrogURL (custom base URL) and joinKey.
Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
./install.sh
```

Start the Xray services on the master node.

Linux Archive

$JFROG_HOME/xray/app/bin/xray.sh start

Docker Compose

docker-compose -p xray up -d

RPM/Debian

systemctl start xray

Upgrade Xray on the secondary nodes.
Linux Archive/Docker Compose
```
./config.sh
```
RPM/Debian
```
config.sh/install.sh
```

Start the Xray services on the secondary nodes.

Linux Archive

$JFROG_HOME/xray/app/bin/xray.sh start

Docker Compose

docker-compose -p xray up -d

RPM/Debian

systemctl start xray

Requirement	Template
Xray	`docker-compose.yaml`
RabbitMQ	docker-compose-rabbitmq.yaml
PostgreSQL	`docker-compose-postgres.yaml`

Content

Space Tools

Upgrading Xray

Overview

Upgrade Steps

SELF-HOSTED

Upgrading from Version Below 2.7

Upgrading from Version 2.7 to 3.x

Interactive Script Upgrade (recommended)

Manual RPM Upgrade

Manual Debian Upgrade

HA Upgrade

Docker Compose

RPM/Debian

Upgrading the First Node

Upgrading the additional Node

Upgrading from Version 3.x to 3.x

Interactive Script Upgrade (Recommended)

Manual RPM/Debian Upgrade

Manual Docker Compose Upgrade

Linux Archive Upgrade

Helm Upgrade

Upgrading the Chart Versions from 1.x/2.x to 3.x and Above

PostgreSQL Migration Process

Prerequisite Step: Get the Details of the Existing Chart

Migrate the Existing MongoDB Data to an Existing PostgreSQL

Perform a Full Database Export and Import of PostgreSQL

RabbitMQ Migration Process

Migrating without Existing Queues

Migrating with Existing Queues

HA Upgrade

Upgrade from Versions Higher than 3.31.0

Upgrade from Versions Prior to 3.31.0