Sessions 3.0.9 to 4.0.2 Single Server 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.

Follow this instruction if you want to upgrade qTest Sessions 3.0.9 to version 4.0.2 on separated CentOS/Ubuntu Machine.


  • This is the instruction to upgrade qTest Sessions 3.0.9 to 4.0.2. If you are using older version of qTest Sessions, you need to upgrade it to 3.0.9 first before upgrading to qTest Sessions 4.0.2
  • qTest Sessions 4.0.2 only works with qTest Manager 8.7.3 or later
  • This guideline is verified on CentOS 7 and Ubuntu 16. If you are using other versions, please contact our Customer Support

Before you begin

Upgrade qTest Sessions


1. 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.

1.1 Access to qTest Sessions server

1.2 Open Terminal

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

# sudo su

1.4 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.

2. Stop qTest Sessions

Execute below command to stop current running qTest Sessions

# service explorerd stop

3. Upgrade system packages


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


# yum check-update && yum update

4. 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

5. 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

1.1 Ensure sessions is included in the apps list

apps = ['sessions']

5.2 Configure database

Go to postgres section and use database configurations we collected in step #1 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'

5.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 #1 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 = '/home/ubuntu/explorer-api/storage'

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

5.4 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. 

5.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 5.6.

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 QASymphony 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.

5.6 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

6. Disable qTest Sessions 3.0.9 service

Enter following command to turn off qTest Sessions 3.0.9

# systemctl disable explorerd

You have successfully upgrade to qTest Sessions 4.0.2. Now you can navigate to qTest Sessions and validate the new version.


Powered by Zendesk