Sessions 3.0.9 to 4.0.2 Single Server Upgrade Guide for Windows

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


  • This is the instruction to upgrade qTest Sessions v3.0.9 (or v3.0.10) to v4.0.2
  • If you are using older versions, you will need to upgrade to qTest Sessions 3.0.9 first before proceeding to this versions
  • qTest Sessions 4.0.2 only works with qTest Manager 8.7.3 or later

Before you begin

Upgrade qTest Sessions


1. Collect current Sessions configurations

Right click on qTest Sessions icon in the system tray, then select 'Configure Instance...'


Note down all the configuration values including: running ports, database configurations, storage configurations, qTest Manager configurations. As highlighted in below screenshots.

qTest Sessions running ports:


Database configurations:


Storage configurations:


qTest Manager configurations


2. Stop qTest Sessions

Right click on qTest Sessions icon in system tray, go to qTestSessionService - Running menu group and select Stop menu item 


3. Install qtestctl

Download qtestctl at <DOWNLOAD LINK>

Extract downloaded file to a folder on disk, e.g. C:\qtestctl

To configure qTest Sessions, navigate to extracted folder C:\qtestctl and edit ‘qtest.config’ file in your favorite text editor.

3.1 Make sure there is sessions item in apps list

apps = ['sessions']


3.2 Configure database

Configure database using the database configurations we collected in step #1.

  • postgres
    • host: Postgres server’s host name or ip address
    • port: Postgres server’s port
  • auth
    • user: username to authenticate with Postgres database server
    • pass: password to authenticate with Postgres database server
  • db:
    • qtest: qtest database’s name
    • session: session's database name
external {
  postgres {
    host = ''
    port = 5432
  auth {
      user = 'postgres'
      pass = 'root'   
  db {
      qtest = 'qtest'
      session = 'sessions'

3.3 Configure qTest Sessions server

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 section sessions to configure qTest Sessions server.

  • 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
    • cert: absolute path to .cert file
  • 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 either on disk or Amazon S3 storage. Make sure you change value of rootpath to reflect actual folder in the machine
    • 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:

sessions {
port: 9443
ssl {
enabled = false // set to true if you want to enable https
key = "/absolute/path/to/dist/ssl/server.key"
cert = "/absolute/path/to/dist/ssl/server.crt"
qtest {
host = ''
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 resources on Amazon S3
accesskey = ''
secretkey = ''
bucketname = ''
// if stores resources on local disk
rootpath = 'C:\\qTest Sessions\\qTest Sessions Storage'


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

3.4 Backup data

Open command prompt and navigate to the extracted folder C:\qtestctl

Enter following command to backup qTest Sessions data.

C:\qtestctl> qtestctl sessions:backup

If the execution is successful, the backed up data is stored in C:\qtestctl\sessions\build\tmp

3.5 Install and start qTest Sessions 

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

If this step is successful, proceed to step 3.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

C:\qtestctl> qtestctl sessions:restore

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

  • Start qTest Sessions 3.0.9 by right clicking on qTest Sessions icon in system tray, go to qTestSessionService - Stopped menu group and select Start menu item
  • 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 restored, contact customer support to troubleshoot the issue with upgrading qTest Sessions.

3.6 Install qTest Sessions as a Windows service

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

We will install qTest Sessions as a Windows service to enable it to automatically starts when Windows starts:

3.6.1 In the Command Prompt, press `ctl + c` if qtestctl is running or open a Command Prompt if you haven't done so, and navigate to the folder C:\qtestctl

3.6.2 Execute below command in your command prompt:

C:\qtestctl> Install.bat
C:\qtestctl> net start qtest


3.7 Turn off qTest Sessions v3.0.9

Right click on qTest Sessions icon in the system tray, and select Exit.

Open command prompt and type 'services.msc' then press Enter. The Services window will be opened.

On Services window, look for a service named 'qTest Sessions Service v3.0.x', then right click on it and select Stop from popup menu.


Right click again on the service qTest Sessions Service v3.0.x then select Properties


Change Startup type to Disabled, and click OK.


You have finished upgrading qTest Sessions to version 4.0.2, now you can access to qTest Sessions site and verify the new version.

Powered by Zendesk