Overview

Xray is composed of several micro services; some are core to Xray while others are third party services such as MongoDB or PostgreSQL. One of the micro services is the Xray installer which, in addition to initial installation, is also responsible for the upgrade process allowing you to upgrade frequently without the risk of losing data. As a result, the process of upgrading Xray is very similar to the installation process. 

When upgrading Xray to version 1.8 and above, from a version below 1.8:
  • Make sure the DB sync completes successfully
  • If you're synchronizing Xray with the Global Database Server in offline mode, to complete the upgrade process, you need to perform a manual offline database sync using the version 1.10.0 and above.

 

As part of the installation/upgrade Xray creates a log file to track the installation process. Each installation/upgrade will create a new install log file with the following format:

${INSTALLER_DIR}/${SCRIPT_NAME}.${DATE}.log


If you are upgrading to version 2.7x from a lower version, and proceeding to upgrade to version 3.x, verify that all data migrations are complete before upgrading 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.

To install/upgrade Xray using automation, add the following to your environment variables and the xray-env.cnf file:

USE_DEFAULTS=true

Existing parameters will be used in the automation process.

 


Upgrading Xray HA

When upgrading an HA cluster, the procedure for upgrading each node is similar to upgrading a single instance (Non-HA) installation, however, there are additional actions required for the nodes to operate as a high availability cluster.

If you are upgrading an Xray HA cluster, please refer to Upgrading an HA Cluster.

Upgrading on Docker

Upgrading Xray's Docker distribution is done using the latest installation script that you need to download from the .

JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

From version 1.10, Xray gives you the option of using your own MongoDB or PostgreSQL databases if you have these already installed and in use in your organization.

If you wish to use your own external database, you first need to perform a number of preliminary operations before upgrading Xray.

For more details, please refer to Using External Databases.

After downloading the latest installation script from the , to upgrade your Xray installation, follow the steps below:

  1. Give the installation script "execute" privileges on your machine.

    chmod +x xray

  2. Stop your current Xray instance: 

    xray stop

  3. Run the upgrade command on the installation script

    xray upgrade

  4. Start xray

    xray start

To use an external database, that’s already installed in your organization, follow the process described here.

Interacting with Installation Script

In addition to managing installation and upgrade, the installation script can provide additional information or perform additional tasks on your installation such as restarting Xray, displaying log files and more. For details, run:

xray help

Upgrading on Linux

Xray is supported on a variety of flavors of Linux and follows standard conventions for folder structure. For details, please refer to Linux Installation. 

To upgrade Xray running on Linux, follow the instructions below replacing <linux-flavor> with the flavor you are using:

JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

From version 1.10, Xray gives you the option of using your own MongoDB or PostgreSQL databases if you have these already installed and in use in your organization.

If you wish to use your own external database, you first need to perform a number of preliminary operations before upgrading Xray.

For more details, please refer to Using External Databases.

  1. Download the latest installation script for your Linux distribution from the. The installation script is used for a variety of functions, and is also used for the upgrade process

  2. Extract the downloaded installation archive to a temporary folder /tmp

    tar -zxvf xray-<linux-flavor>-latest.tar.gz

  3. Run the installation script located in the extracted folder
    (if you are not running as "root", prepend the following command with "sudo")

    ./installXray-<linux-flavor>.sh

To use an external database, that’s already installed in your organization, follow the process described here.

Interacting with Installation Script

The installation script offers several facilities for maintenance. For details, please refer to Interacting with the Linux Installer. 

Modifying Default File Locations

When upgrading your Xray installation, the installation script places files in default locations.

For the Xray data files and PostgreSQL home directory, you may modify the location from the default. For details, please refer to the README file in your Xray home directory.

Upgrading the Database

In some cases, when upgrading Xray to the latest version, Xray also needs to update its database (for example, if the database schema changes). While Xray handles this internal upgrade process automatically, it is a process which may take some time, and it is important that you don't interrupt the upgrade process and let it run to completion. During the upgrade process, Xray will provide a visual indication of its progress.

Database upgrade

In case of an issue, Xray will stop the upgrade process and will provide error information which you can share with JFrog support for further help, this can be also troubleshooted.

DB Upgrade Error

Using External Databases

JFrog Xray uses several databases for different features of its operation. Until version 1.10, Xray installed an instance of all of these databases dedicated for its own use.

From version 1.10, Xray gives you the option of using your own MongoDB or PostgreSQL databases if you have these already installed and in use in your organization.

Xray currently supports the following versions for each of these databases:

postgres:9.5.2
mongo:3.2.6


It is up to you to choose which, if any of these databases to externalize when you upgrade Xray.

 If you choose to have Xray use any of your own databases for its operation, you take full responsibility for the maintenance, monitoring, backup and correct functioning of these databases.

You only need to follow the process below to use your own database once. Subsequent upgrades can be performed as usual, without having to follow the process below. 

To use your own databases with Xray, follow the procedure below:

  1. Stop Xray microservices

    ./xray.sh stop

  2. Back up the Xray configuration file using the following command:

    mv <XRAY_HOME_FOLDER>/config/xray_config.yaml <XRAY_HOME_FOLDER>/config/xray_config_orig.yaml

    During the upgrade process, the default configuration file will be recreated in the same location.

  3. Do a DB dump to back up all the databases that you want Xray to use (i.e. those which you are externalizing for Xray).

  4. Stop all the external databases that you want Xray to use 

    ./xray.sh stop all

  5. Prepare all the external databases that you want Xray to use by adding the required schema as described in the corresponding snippets below:

    //Creating default admin user
var adminUser = {
    user:"admin",
    pwd: "password",
    roles: ["root"],
    customData: {
        createdBy: "JFrog Xray installer"
    }
}
db.getSiblingDB("admin").createUser(adminUser)

//Creating default xray user
var xrayUser = {
    user:"xray",
    pwd: "password",
    roles: ["dbOwner"],
    customData: {
        createdBy: "JFrog Xray installer"
    }
}

//Authenticating as admin to create xray user
var loginOutput = db.getSiblingDB("admin").auth(adminUser.user,adminUser.pwd)
db.getSiblingDB("xray").createUser(xrayUser) 
    CREATE USER xray WITH PASSWORD 'xray';
CREATE DATABASE xraydb WITH OWNER=xray ENCODING='UTF8';
GRANT ALL PRIVILEGES ON DATABASE xraydb TO xray;

  6. Purge your current installation of Xray:

    With Aptitude:
apt-get purge xray
 
With YUM:
yum erase xray

  7. Manually clean up your previous installation

    Purging your previous installation of Xray only removes Xray's configuration folder found, by default, at /opt. 

    Therefore, after purging your previous version, make sure to clean any residual database files left in your system and the data folder found, by default, at /var/opt.

  8. Continue with upgrading Xray as described in Upgrading on Docker or Upgrading on Linux according to your installation type.