Upgrading Xray

Upgrading Xray HA

Upgrading on Docker

After downloading the latest installation script from the  Xray Download Page, 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

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:

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

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.

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.

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.

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

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.