Cloud customer?
 Upgrade in MyJFrog >

Search





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.

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 instances 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 >


Upgrade Steps

The upgrade procedure involves the following steps:

  1. Download Xray (Docker Compose, RPM, Debian).
  2. Stop the Xray service
  3. Install Xray according to the distribution type.
  4. Check the Migration Log and review system.yaml to validate the migration was successful (only for upgrading from v3.x).
  5. Start the service using the start scripts or OS service management.
  6. 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.

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.


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 Upgrade (recommended)

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

  1. Download Xray (RPM, Debian or Docker Compose).
  2. 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
  3. 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.

  4. 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. 
  5. 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
  6. 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. 

  7. 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 system.yaml. Note that this flag is not consumed in docker-compose installation.

    systemv OS
    service xray start
    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
    
  8. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.
  9. 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:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. 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.

  1. Download Xray (RPM).
  2. Stop the current service.

    cd /opt/jfrog/xray/scripts
    ./xray.sh stop
  3. 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
  4. Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.
  5. Install Xray as a service on Red Hat compatible Linux distributions, as a root user.

    yum -y install ./xray/xray.rpm
  6. 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. 

  7. 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 Administration module | Security | 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.

  8. Make sure the third party services are running.

    PostgreSQL

    If you had installed PostgreSQL database which was packaged as part of 2.x, 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, MongoDB will not be used by Xray except during the migration phase. On start of version 3.x, data will be 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 will depend on the data size to be migrated.

    service mongod start|stop|status
  9. Start Xray.

    systemd OS
    systemctl start xray.service
    systemv OS
    service xray start
  10. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  11. 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:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. 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.

  1. Download Xray (Debian).
  2. Stop the current server.

    cd /opt/jfrog/xray/scripts
    ./xray.sh stop
  3. 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
  4. Make sure your MongoDB is running, to ensure that the migration process to PostgreSQL will work.
  5. Install Xray as a service on a Debian compatible Linux distributions, as a root user.

    Run Installation
    dpkg -i ./xray/xray.deb
  6. 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. 

  7. 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 Administration module | Security | 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.

  8. Make sure the third party services are running.

    PostgreSQL

    If you had installed PostgreSQL database which was packaged as part of 2.x, 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, MongoDB will not be used by Xray. 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. This can be uninstalled after Xray 3.x is successfully installed and running.

    service mongod start|stop|status
  9. Start Xray.

    systemd OS
    systemctl start xray.service
    Systemv OS
    service xray start
  10. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.
  11. 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:

  1. Validate that your Xray data has migrated successfully.
  2. Remove MongoDB configuration from the system.yaml.
  3. 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

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.

  1. Stop all the cluster nodes that are setup using HA by running the following command on each node.

    ./xray stop all
  2. 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.

  3. 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.

  4. Start the node. Note:Run this commandonlyfrom  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



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

    docker-compose -p xray logs
  6. Check Xray Log.

RPM/Debian

Upgrading the First Node

  1. 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.

  2. 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
  3. Run the install.sh script to setup folders with required ownership.

    ./install.sh
  4. Add the following to the $<PostgreSQL home folder>/data/pg_hba.conf file.

    host    all             all             0.0.0.0/0               md5
  5. Add the following to the $<PostgreSQL home folder>/data/postgresql.conf file.

    listen_addresses='*'


  6. 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.

  7. Start the Xray node.

    systemd OS
    systemctl start xray.service
    systemv OS
    service xray start

    Manage Xray using the following commands.

    systemd OS
    systemctl stop xray.service
    systemv OS
    service xray stop|status|restart
  8. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.
  9. Check Xray Log.

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

Upgrading the additional Node

  1. Stop all the cluster nodes that are setup using HA by running the following command on each node.

    service xray stop


  2. 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
  3. Run the config.sh script to setup folders with required ownership.

    ./install.sh
  4. 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>
  5. Start the Xray node.

    systemd OS
    systemctl start xray.service
    systemv OS
    service xray start

    Manage Xray using the following commands.

    systemd OS
    systemctl stop xray.service
    systemv OS
    service xray stop|status|restart
  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.
  7. 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:

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



Upgrading from Version 3.x to 3.x

The following upgrade methods are supported:

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 install Xray and its dependencies.

  1. Download Xray (RPM, Debian or Docker Compose).
  2. 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
  3. 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.

  4. Run the installer script.
    Note: 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
  5. Start the Xray service.

    systemd OS
    systemctl start xray.service
    systemv OS
    service xray start
    Docker Compose
    cd jfrog-xray-<version>-compose
    docker-compose -p xray up -d
  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.
  7. Check Xray Log.

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

Manual RPM/Debian Upgrade

  1. Download Xray (RPM or Debian)

  2. Stop the current server.

    systemd OS
    systemctl stop xray.service
    systemv OS
    service xray stop
  3. 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>
  4. 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
  5. Start Xray.

    systemd OS
    systemctl start xray.service
    systemv OS
    service xray start
  6. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Security & Compliance tab in the Application module in the UI.

  7. Check Xray Log.

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

Linux Archive Upgrade

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

  1. Stop the current server.

    Stop Xray
    cd $JFROG_HOME/xray/app/bin
    ./xray.sh stop
  2. 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
  3. 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
    
  4. Manage Xray.

    $JFROG_HOME/xray/app/bin/xray.sh start|stop
  5. Access Xray from your browser at: http://<jfrogUrl>/ui/, go the Dashboard tab in the Application module in the UI.
  6. Check Xray Log.

    tail -f $JFROG_HOME/xray/var/log/console.log
  • No labels
Copyright © 2020 JFrog Ltd.