Sessions 3.0.9 to 4.0.2 Load Balancer Upgrade Guide for Linux (non-Docker)

To request assistance with upgrading or to obtain the links to self-upgrade, please click here to fill out the Upgrade Request Form.

This article is for upgrading qTest Sessions to version 4.0.2 on Load Balancing environment where multiple qTest Sessions instances are installed and each instance is running on separated CentOS/Ubuntu server.


You have already installed earlier version qTest Sessions on Load Balancing environment, and the running version of qTest Sessions is 3.0.9.

Below is a specific scenario of installing qTest Sessions on Load Balancing environment. Highlighted items are qTest Sessions and components it needs to run. This article will cover upgrading qTest Sessions application nodes, which is qTest Sessions Server #1 and qTest Sessions Server #2



Upgrade to qTest Sessions 4.0.2

To upgrade to qTest Sessions version 4.0.2, you need to access to every server that qTest Sessions is installed, download the new version then perform the upgrade.

This instruction will walk you through upgrading qTest Sessions in one server, but you can do the same on other servers that installed qTest Sessions as well.

1. Access to qTest Sessions server

2. Open Terminal

3. Ensure you will run all the upgrade commands as system user by executing the following command

# sudo su

4. Stop qTest Sessions service

# service explorerd stop

5. Collect current configurations

Follow steps below to collect current configuration of qTest Sessions 3.0.9. We will use these information later to upgrade to qTest Sessions 4.0.2.

Go go qTest Sessions 3.0.9 installation folder and execute below command to view the configurations:


/usr/local/sessions-linux-3.0.9# vim conf/


/usr/local/sessions-linux-3.0.9# vi conf/

Note down all the configuration values, including:

  • Postgres server and database configurations
  • qTest configurations
  • qTest Sessions configurations
  • Storage configurations

Below is an example of configuration values that we will use in our upgrading process, in bold.

# database configuration

# redis configuration

# qtest configuration

# elastic search configuration


# qtest sessions application information.

# declare eXplorer API url to use.
# storage configuration
# storage.type suitable value (disk | s3 | riakcs)

# disk storage configuration.

6. Upgrade system packages

On Ubuntu:

# apt-get update && apt-get upgrade
# apt-get install libfontconfig

On CentOS:

# yum check-update && yum update

7. Download qtestctl

Changed to /usr/local directory and execute below commands to download qtestctl

# cd /usr/local
/usr/local# wget <ENTER DOWNLOAD LINK HERE>

Unzip and navigate to qtestctl folder

/usr/local# tar xzvf <DOWNLOADED PACKAGE FILE NAME> 
/usr/local# cd qtestctl

8. Configure qtestctl

We will configure qTest Sessions in qtest.config file. Below command will open qtest.config file in vim editor.


/usr/local/qtestctl# vim qtest.config
Press Insert to edit the config file


/usr/local/qtestctl# vi qtest.config
Press insert to edit config file

8.1 Ensure sessions is included in the apps list

apps = ['sessions']

8.2 Configure database

Go to postgres section and use database configurations we collected in step #5 to configure qTest Sessions database.

  • host: postgres database server’s host name or ip address
  • port: postgres database server’s port
  • auth: configure database authentication credentials
    • user: qTest Sessions database user name
    • pass: qTest Sessions database user password
  • db: configure qTest Sessions database
    • qtest: qTest database name
    • session: qTest Sessions database name
external {
  postgres {
    host = ''
    port = 5432
  auth {
      user = 'postgres'
      pass = 'admin123'   
  db {
      qtest = 'qtest'
      session = 'sessions'

8.3 Configure qTest Sessions server

In this step, we will use qTest Sessions running ports, storage configurations, and qTest Manager configurations that we collected in step #5 to configure qTest Sessions server.

In qTest.config file, navigate to sessions section and enter below configurations:

  • port: configure server port that qTest Sessions will be listening
  • ssl: configure SSL if you want to deploy qTest Sessions with https protocol
    • enabled: set value to true to enable https
    • key: absolute path to .key file. Only affected if enabled field is set to true
    • cert: absolute path to .cert file. Only affected if enable is set to true
  • qtest: configure qTest Manager application URL and master token
    • host: qTest Manager URL
    • mastertoken: the token that qTest Sessions uses to connect to qTest Manager
  • storage: configure a location that qTest Sessions will store its data to
    • type: type of the storage, possible value is amazon_s3 or disk_storage
    • accesskey: if storage type is set to amazon_s3, this is the access key used to access to Amazon S3 storage. Leave this field empty if storage type is set to disk_storage
    • secretkey: if storage type is set to amazon_s3, this is the access key used to access to Amazon S3 storage. Leave this field empty if storage type is set to disk_storage
    • bucketname: if storage type is set to amazon_s3, this is ame of the name of the bucket to store data on Amazon S3
    • rootpath: if storage type is set to disk_storage, this is the absolute path to a folder on disk where data is stored

Below is an example of qTest Sessions server configuration, in bold.

sessions {
port: 9090
ssl {
enabled = false
key = "/absolute/path/to/dist/ssl/server.key"
cert = "/absolute/path/to/dist/ssl/server.crt"
qtest {
host = ''
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 stores resources on Amazon S3
accesskey = ''
secretkey = ''
bucketname = ''
// if stores resources on local disk
rootpath = '/session-storage'

Save and close qtest.config file when you are done. 

9. Backup data

From Terminal, navigate to /qtestctl directory and enter below command to make sure qtestctl has 'execute' permission

# sudo chmod +x qtestctl

Enter following command to backup qTest Sessions data

# qtestctl sessions:backup

If the command is successful, the backed up data will be stored in \qtestctl\sessions\build\tmp. 

4.5 Start qTest Sessions 

# qtestctl sessions:start
Done configuration qTest site
Done configuration storage
<===========--> 85% EXECUTING [57m 45s]
> :sessions:start

If this step is successful, proceed to step 10.

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

Restore backup data

# qtestctl sessions:restore

When restore process completed, perform the following step to completely rollback to qTest Sessions 3.0.9:

  • Go to qTest Sessions 3.0.9 installation folder and start it
    • /usr/local/sessions-linux-3.0.9# service explorerd start
  • Open <qTest Sessions URL>/admin page. Here <qTest Sessions URL> is the URL to access to your  qTest Sessions 3.0.9
  • Login with your admin account. Note: consult QAS customer support for the admin credentials
  • Go to elasticsearch menu item in the left panel
  • Click on 'Reindex Data' button

After that, contact customer support to troubleshoot the issue with upgrading qTest Sessions.

10. Install qTest service

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

Note: only proceed to this step when you successfully performed step 4.5.

From Terminal, press 'Ctrl + C' if qtestctl is running

Execute below command to install qtestctl as a service

# ./install

Verify qtest service has been successfully installed and running with following command

# systemctl status qtest
qTest has successfully started!

However, if you see:

Active: inactive (dead)

then enter following command to start the service

# systemctl start qtest

11. Disable qTest Sessions 3.0.9 service

Enter following command to turn off qTest Sessions 3.0.9

# systemctl disable explorerd

Repeat step #1 to #11 to upgrade qTest Sessions on qTest Sessions Server #2.

When you are done, you can navigate to qTest Sessions and validate the new version.


Powered by Zendesk