Upgrading from Xray 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.

Upgrading from Xray 2.x to the latest version of Xray

Starting from version Xray 3.88.10, you can no longer upgrade Xray 2.x directly to the latest version of Xray. You must upgrade from Xray 2.x to 3.87.x, and then upgrade to the latest version of Xray.

The following upgrade methods are supported:

Warning

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 comes 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 contains your current custom configurations in the new format.
  Warning
  Ensure that a large file handle limit is specified before you start Xray.

Start the Xray service.

systemd OS

systemctl start xray.service

Note

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 thesystem.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.
  Warning
  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 thesystem.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.
  Warning
  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 thesystem.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:

Warning

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.

Note

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.

Note

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.
Check Xray Log.
```
docker-compose -p xray logs
```

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
```
Note
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
```
Note
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 thesystem.yaml.
Uninstall the MongoDB database.

Upgrading from Xray 2.x to the latest version of Xray

Warning

Migrating data from MongoDB to PostgreSQL

Interactive Script Upgrade (recommended)

.env file included within the Docker-Compose archive

.env in Docker-Compose

Warning

Note

Post Data Migration Steps (MongoDB to PostgreSQL)

Manual RPM Upgrade

Warning

PostgreSQL

RabbitMQ

Migrating data from MongoDB to PostgreSQL

Post Data Migration Steps (MongoDB to PostgreSQL)

Manual Debian Upgrade

Warning

PostgreSQL

RabbitMq

MongoDB

Post Data Migration Steps (MongoDB to PostgreSQL)

HA Upgrade

Upgrading an Xray 2.x HA Cluster

Warning

Docker Compose

Note

.env file included within the Docker-Compose archive

Note

RPM/Debian

Upgrading the First Node

Note

Note

Upgrading the additional Node

Post Data Migration Steps (MongoDB to PostgreSQL)