To request assistance with upgrading or to obtain the links to self-upgrade, please click here to fill out the Upgrade Request Form.
Before you begin
- This is the instruction to upgrade qTest Sessions v3.0.9, 3.0.10 to v4.0.2 on cluster or load balancing environment, where multiple instances of qTest Sessions were installed, and each instance is running on its own Windows server
- qTest Sessions v4.0.2 only works with qTest Manager v8.7.3 or later
- Make sure qTest Manager is running and your qTest license file has been imported
- Make sure your server environment meets recommended hardware requirements
Below diagram shows a sample scenario of qTest Sessions 3.0.9 being installed on a cluster or load balancing environment.
Steps to upgrade to qTest Sessions 4.0.2 on Load Balancing environment
You will need to access to every Windows instance where qTest Sessions was installed (qTest Sessions Server #1 and qTest Sessions Server #2 in the above diagram) and perform steps to upgrade qTest Sessions to v4.0.2.
Step 1. Login to qTest Sessions Server
Step 2. Collect current qTest 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:
qTest Manager configurations
Step 3. Stop qTest Sessions
Right click on qTest Sessions icon in system tray, go to qTestSessionService - Running menu group and select Stop menu item
Step 4. Install qtestctl and Configure qTest Sessions
Download qTest Sessions 4.0.2 at <DOWNLOAD LINK>
Extract downloaded file to C:\qtestctl
To configure qTest Sessions, navigate to extracted folder C:\qtestctl and edit ‘qtest.config’ file
Step 4.1. Make sure there is sessions item in apps list
apps = ['sessions']
Step 4.2. Configure qTest Sessions database
Go to postgres section and use the database configurations we collected in step #1 to configure database for qTest Sessions
- host: Postgres server’s host name or ip address
- port: Postgres server’s port
- user: username to authenticate with Postgres database server
- pass: password to authenticate with Postgres database server
- qtest: qtest database’s name
- session: session's database name
host = '10.0.10.25'
port = 5432
user = 'postgres'
pass = 'root'
qtest = 'qtest'
session = 'sessions'
Step 4.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 in qtest.config file 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. In our example, we will use S:\
Below is an example of qTest Sessions server configuration:
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"
host = 'http://22.214.171.124:8080'
// 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 = 'S:\\'
Save and close qtest.config file when you are done.
Step 5. Backup data
Open command prompt and navigate to the extracted folder \qtestctl
Enter following command to backup qTest Sessions data.
> qtestctl sessions:backup
If the execution is successful, the backed up data is stored in \qtestctl\sessions\build\tmp
Step 6. Start qTest Sessions
> qtestctl sessions:start
If this step is successful, proceed to step #7.
Troubleshooting: if step above is not successful, you need to rollback qTest Sessions to version 3.0.9 (or 3.0.10) 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:
- 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 in this server
- 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 on the right
After restored, contact customer support to troubleshoot the issue with upgrading qTest Sessions on Windows load balancing environment.
Step 7. Install qTest Sessions as a Windows service
Note: only proceed to this step when you have successfully performed step #6.
To enable qTest Sessions to automatically starts when Windows starts, we need to install it as a Windows service.
Open a Command Prompt if you haven't done so, and navigate to the extracted folder C:\qtestctl
Execute below command in your command prompt:
C:\qtestctl> net start qtest
Step 8. Turn off qTest Sessions 3.0.9
Note: only proceed to this step when you successfully performed step #6.
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.
Step 9. Repeat step #1 to #8 to upgrade qTest Sessions on another server
Step 10. Verify
This step is to make sure qTest Manager is able to connect to the qTest Sessions through qTest Sessions Load Balancer.
9.1 Login to qTest Manager using Site Administrator account.
9.2 Go to Site Administration page and click on tab SYSTEM CONFIGURATIONS.
9.3 In MISCELLANOUS section, enter URL of qTest Manager, such as http://[qTest_Manager_IPAddress]:[Port] or https://[qTest_Manager_IPAddress]:[Port] if you installed qTest Manager with SSL certificate.
9.4 In QTEST EXPLORER | SESSIONS section, ensure the value of qTest Explorer | Sessions URL field is set to the public IP address of qTest Sessions Load Balancer, as below screenshot.
Now you can access to qTest Sessions site and verify the new version.