Skip to end of metadata
Go to start of metadata

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

Database Sync Required

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 JFrog CLI version 1.10.0 and above.

 

Installer Log

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

 

Using non-interactive automated scripts to install Xray

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.


Page contents


Upgrading Xray HA

There are different instructions for 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

Download the installation script

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

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.

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  Xray Download Pageto 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

Using External Databases

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:

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.

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 Xray Download Page. 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

Using External Databases

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.

Supported versions

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.

You take full responsibility for your own databases

 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.

Only externalize once

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:

     Click for snippet to add the required schema to MongoDB...
    Adding the required schema to MongoDB
    //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) 
     Click for snippet to add the required schema to PostgreSQL...
    Adding the required schema to PostgreSQL
    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

    Manual cleanup required

    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.


  • No labels