Menu

Sessions 4.0.2 to 4.1 Single Server Upgrade Guide for Linux (non Docker)

Overview

In this article, we provide step-by-step instructions to upgrade qTest Sessions 4.0.2 to 4.1 on a single CentOS/Ubuntu Machine. Please read the instructions thoroughly before starting your installations.

To request assistance with upgrading or obtain the self-upgrade links, complete the Upgrade Request Form and reference the OnPremise Upgrades Guide.

Note: If you are performing a fresh install, use the OnPremise New Install Form and reference the OnPremise Install Guide.

Before You Begin

  • qTest Sessions 4.1 only works with qTest Manager 9.0 or later.
  • This guideline is verified on CentOS 7 and Ubuntu 16. If you are using other versions, please contact our Customer Support.
  • If you are using an older version, you will need to upgrade to qTest Session 4.0.2 before proceeding to this version.

Read the following:

Collect Current Configurations

Follow the steps below to collect current configurations of qTest Sessions 4.0.2. You will uthis informationion later to upgrade to qTest Sessions 4.1.

  1. Access the qTest Sessions server.
  2. Open the Terminal.
  3. Run all of the upgrade commands as a system user by executing the following:
    # sudo su
  4. Navigate to the qTest Sessions 4.0.2 installation folder and execute the commands below to view the configurations:
    Ubuntu
    /usr/local/qtestctl# vim qtest.config
    CentOS
    /usr/local/qtestctl# vi qtest.config
  5. Write down all the configuration values, including:
    • PostgreSQL server and database configurations
    • qTest Sessions configurations
    • Storage configurations

Below is an example of configuration values,  in blue, that you will collect and use in the upgrade process.

# database configuration
postgres {
  host = '[PostgreSQL server's IP or hostname]'
  port = '[PostgreSQL server's Port]'
  auth {
    user = '[PostgreSQL username]'
    pass = '[PostgreSQL password]'   
}
  db {
    qtest = '[Database name of qTest Manager]'
    session = '[Database name of qTest Sessions]'
  }
}
...
sessions {
  port = [qTest Sessions Running Port]
ssl {
  enabled = false
    key = '/absolute/path/to/dist/ssl/server.key'
   cert = '/absolute/path/to/dist/ssl/server.crt'
 

qtest {
    host = '[http or https]://[qTest Manager's IP or Hostname]:[Port]'
   mastertoken = "QToy"
}
storage {
// value must in ['amazon_s3', 'disk_storage']
// * amazon_s3: stores resource files on amazon ec2
// * disk_storage: stores resource files on local disk
type = "disk_storage"
// If stores resource on EC2
accesskey = ‘’
secretkey = ‘’
bucketname = ‘’
// If stores resource on local disk
rootpath = '/path/to/sessions/resources'
}
}

Stop qTest Sessions

From the Terminal, execute this command to stop running qTest Sessions 4.0.2:

# service qtest stop

Upgrade to qTest Sessions 4.1

Download qtestctl

If you plan to upgrade qTest Sessions 4.1 in the same server with other qTest application(s), e.g. qTest Manager, then you do not need to re-download the package. Otherwise, download the new package at <DOWNLOAD LINK>.

Note: to learn more about qtestctl, refer to this article qTest OnPremise - Technical detail about qtestctl

  1. Assume that the qTest Sessions package is extracted to /usr/local/qtestctl-4.1
  2. Navigate to the extracted directory:
     /usr/local/qtestctl-4.1
  3. Open and edit qtest.config file in your vim text editor:
    Ubuntu
    /usr/local/qtestctl-4.1# vim qtest.config
    Press Insert to edit the config file
    CentOS
    /usr/local/qtestctl-4.1# vi qtest.config
    Press insert to edit config file 

Configure Applications

  • If you are upgrading qTest Sessions on a separate machine, make sure there is a sessions item in the apps list.
apps = ['sessions']
  • If you are upgrading qTest Sessions on the same server with other qTest applications, e.g. qTest Manager, append sessions to the app list.
apps = ['manager', 'sessions']
 

Configure qTest Sessions Database

Navigate to the postgres section in the qtest.config file shown below to configure the qTest Sessions database. Use the collected database configurations in blue. Only the information listed below in blue should be updated, all other data should remain unchanged.

 

external {
postgres {
   host = '[PostgreSQL server's IP or hostname]'
   port = '[PostgreSQL server's Port]'
  auth {
     user = '[PostgreSQL username]'
     pass = '[PostgreSQL password]'   
}
  db {
     qtest = '[Database name of qTest Manager]'
     session = '[Database name of qTest Sessions]'
   }
}
  ...
}

Configure SSL

If you want to deploy qTest Sessions with SSL, navigate to the section common in the qTest.config file as shown below.
IMPORTANT: Replace the blue text in the brackets with your custom values. Only the information listed below in blue should be updated, all other data should remain unchanged

  • enable: set to true to enable a secure connection (HTTPS) between the user browser and the server. Default value is false.
  • cert: absolute path to the certificate file on this server. Please use \\ or / in the path. It is mandatory if enable is set to true.
  • key: absolute path to the private key file on this server. Please use \\ or / in the path. It is mandatory if enable is set to true.
  • pass: passphrase of your certificate. This field is optional (default value is empty).
  • strict: set this to false to allow self-signed SSL certificate.
common {
ssl {
enabled = false
cert = "${path}/server.crt"
key = "${path}/server.key"
pass = ""
strict = false
}
}

Configure qTest Sessions Server

  1. In the qtest.config file, navigate to the sessions section, shown below to configure your qTest Sessions server. Use the collected database configurations in blue. Only the information listed below in blue should be updated, all other data should remain unchanged.
  2. Save and close qtest.config file when you are done.

 

...
sessions {
port: [qTest Sessions Running Port]
...
qtest {
host = '[http or https]://[qTest Manager's IP or Hostname]:[Port]'
mastertoken='QToy'
}
storage {
// value must be in ['amazon_s3', 'disk_storage']
// * amazon_s3: stores resource files on amazon ec2
// * disk_storage: stores resource files on local disk
type = 'disk_storage'
// if storage type is set to amazon_s3, this is the access key to access to it
accesskey = ''
// if storage type is set to amazon_s3, this is the secret key to access to it
secretkey = ''
// if storage type is set to amazon_s3, this is the bucket where resource files are stored
bucketname = ''
// if storage type is set to disk_storage, this is the path to the directory where resource files are stored
rootpath = '/path/to/sessions/resources'
}
...
}

Backup Data

Run these commands in qTest Sessions 4.0.2's qtestctl fodler.
Example: /usr/local/qtestctl

  1. From the Terminal, enter this command to make sure qtestctl has 'execute' permission:
    /usr/local/qtestctl# sudo chmod +x qtestctl
  2. Enter the following command to backup qTest Sessions data:
    /usr/local/qtestctl# ./qtestctl sessions:backup
  3. If the command is successful, the backed-up data is stored in:
    /qtestctl/sessions/build/tmp.

Start qTest Sessions 4.1

If this step is successful, you can install qTest Sessions.

# cd /usr/local/qtestctl-4.1
/usr/local/qtestctl-4.1# ./qtestctl start
Done configuration qTest site
Done configuration storage
<===========--> 85% EXECUTING [57m 45s]
> :sessions:start
> IDLE

Troubleshooting: if the step above is not successful, you need to rollback qTest Sessions to version 4.0.2 by following the steps below:

  1. Restore backup data by running this command from the qTest Sessions 4.0.2's qtestctl folder.
    Example: /usr/local/qtestctl
    # cd /usr/local/qtestctl
    /usr/local/qtestctl# ./qtestctl sessions:restore
  2. When the restore process completes, perform the following step to completely rollback to qTest Sessions 4.0.2:
    • # systemctl start qtest
    • Contact customer support to troubleshoot the issue with upgrading qTest Sessions.

Install qTest Service

Important: only proceed to this step when you have successfully started qTest Sessions.

To enable qTest Sessions to automatically starts when your OS starts, you need to install qtest service.

  1. Remove the previous qTest Session 4.0.2's service
  2. Navigate to qTest Sessions 4.0.2 folder:
    # cd /usr/local/qtestctl
  3. Execute this command to uninstall the service:
    /usr/local/qtestctl# ./uninstall
  4. Install qTest Sessions 4.1 service
  5. Navigate to /usr/local/qtestctl-4.1.
    # cd /usr/local/qtestctl-4.1
  6. Execute the command below to install qtestctl as a service:
    /usr/local/qtestctl-4.1# ./install
  7. Verify qtest service has been successfully installed and running with the following command:
    # systemctl status qtest
    qTest has successfully started!
    • However, if you see:
      Active: inactive (dead)
    • then enter the following command to start the service:
      # systemctl start qtest
  8. You have successfully upgraded to qTest Sessions 4.1.
  9. Now you can navigate to qTest Sessions and validate the new version.
Powered by Zendesk