Sessions 4.1 Load Balancer Installation Guide for Windows


In this article, we provide step-by-step instructions to install qTest Sessions 4.1 on different Windows server machines with a Load Balancer, then connect it to qTest Manager on another machine. Please read the instructions thoroughly before starting your installations.

To request assistance with installation or obtain the self-upgrade links, complete the OnPremise New Install Form.

Note: If you are not performing a fresh install and are upgrading, use the Upgrade Request Form and reference the OnPremise Upgrades Guide.

Before You Begin

This instruction is specific for deploying qTest Sessions on Windows Server 2012 environment, if you are installing qTest Sessions with load balancing on another Windows version, consult our customer support

  • qTest Sessions 4.1 only works with qTest Manager 9.0 or later.
  • You need to install qTest Manager before installing qTest Sessions.

Read the following:

Install qTest Sessions with Load Balancer

The diagram below demonstrates a sample scenario to deploy qTest Sessions in a Windows load balancing environment.


  • qTest Manager: an instance of qTest Manager deployed in a Windows server
  • qTest Manager DB Server: a server that manages qTest Manager database
  • qTest Sessions Server #1: a server that hosts qTest Sessions application
    • IPv4 Public IP: we will not expose its IP address to the outside world
    • Private IP:
  • qTest Sessions Server #2: another server that hosts qTest Sessions application
    • IPv4 Public IP: we will not expose its IP address to the outside world
    • Private IP:
  • Shared Server: a server that hosts shared components that are required to run qTest Sessions
    • PostgreSQL: a database engine used to manage qTest Sessions data
    • NFS (Network File Systems): used to share directories and files with others over a network. We will use NFS to manage and share files created by qTest Sessions applications deployed on the 2 qTest Sessions servers
    • IPv4 Public IP: we will not use the public IP address since this server will not be exposed to the outside world
    • Private IP:
  • qTest Sessions Load Balancer: a server that acts as a load balancer for the two qTest Sessions servers. We will install and use nginx on this server for that purpose.
    • IPv4 Public IP: We will expose this IP address to qTest Manager so the two applications can connect to each other.
    • Private IP:

Install qTest Manager

Follow one of the below instructions to install qTest Manager on a Windows Server:

After you have installed qTest Manager, note down its IPv4 Public IP address. This is the IP address that qTest Sessions application will connect to.

In our example, qTest Manager IPv4 Public IP address is

Setup Shared Server

Access the shared server (whose private IP address is and install the following applications and/or packages.

Install PostgreSQL

qTest Sessions 4.1 requires PostgreSQL database engine 9.5 or 9.6 (preferred) to be installed. Skip this step if you have already installed PostgreSQL.

Go to this page to download PostgreSQL. After downloading, run the installer to install PostgreSQL on the Shared Server.

Configure PostgreSQL

Make sure you enable remote access to PostgreSQL database server. 

  1. Open file C:\Program Files\PostgreSQL\<version>\data\pg_hba.conf. Note: replace <version> place holder with the actual version that you have installed.
  2. Look for the following line and if it does not exist, append the line to the file.
    host all all md5
    host all all ::1/0 md5
  3. Your C:\Program Files\PostgreSQL\<version>\data\pg_hba.conf now looks like below:
  4. Open the file C:\Program Files\PostgreSQL\<version>\data\postgresql.conf.
  5. Look for the following line, and if it does not exist, append it to the file:
    listen_addresses = '*'
  6. Save and close the file when you have finished.

Restart PostgreSQL Service

Restart PostgreSQL service for the changes to take effect.
Important: By default, PostgreSQL runs on port 5432. You will configure the firewall for this later.

  1. Open the Start menu, and locate your Windows System.
  2. Select Run and type services.msc to open the Services window.
  3. Assume you have installed PostgreSQL 9.5, therefore, on the Services window look for the service named postgresql-x64-9.5.
  4. Right-click on the postgresql-x64-9.5 service and select Restart in the popup menu.


Create qTest Sessions Database

After PostgreSQL has been successfully installed and configured on the shared server, you need to create a database schema for qTest Sessions. 
Important: replace the <version> placeholder in the code below with the actual version of PostgreSQL you are using.

    1. Open the Command Prompt, and change the current path to PostgreSQL installation directory.
      > cd C:\Program Files\PostgreSQL\<version>\bin
    2. Create a database schema using the command below:
      C:\Program Files\PostgreSQL\<version>\bin> createdb -h [YOUR_POSTGRES_SERVER_IP_ADDRESS] -p [YOUR_POSTGRES_SERVER_PORT] -U postgres -W [YOUR_DATABASE_NAME] 
      C:\Program Files\PostgreSQL\<version>\bin>createdb -h -p 5432 -U postgres -W sessions //postgres is the username and sessions is the schema name
      Password: root // in this example we use `root` as the password of the user postgres
    3. Connect to the database:
      C:\Program Files\PostgreSQL\<version>\bin>psql -h -U postgres -W sessions
      Password for user postgres: root // again, we will use `root` as the password of the user postgres
      psql (<version>)
      WARNING: Console code page (437) differs from Windows code page (1252)
               8-bit characters might not work correctly. See psql reference
               >page "Notes for Windows users" for details.
      Type "help" for help.
    4. List out existing schema to verify sessions database schema has been successfully created, as shown below, in bold:
                              \l List of databases
       Name             | Owner    | Encoding |          Collate           |         
       Ctype            | Access privileges
       postgres         | postgres | UTF8     | English_United States.1252English_United States.1252 |
       template0        | postgres | UTF8     | English_United States.1252 | English_United States.1252 |
       sessions         | postgres | UTF8     | English_United States.1252 | English_United States.1252 |
      (3 rows)
    5. Quit psql program.
      postgres-# \q 

Install and Configure NFS

Network File System (NFS) is a Windows component that is used to share files across machines. Follow the instructions below to install and setup NFS.

Install NFS

  1. Open Server Manager, and navigate to the Dashboard.
  2.  Select Add Roles and Features.
  3. Select Next on the 'Before you begin' window.
  4. On the Select installation type screen, make sure the option 'Role-based or feature-based installation' is selected, then select Next.
  5. On the Select destination server screen, make sure the option 'Select server from the server pool' is selected, and select Next.
  6. From the Select server roles screen, locate and expand 'File and Storage Services (2 of 12 installed)' item then expand 'File and iSCSI Services (1 of 11 installed).'
  7. Select the checkbox for 'Server for NFS.'
  8. Select 'Add Features' in the popup.
  9. The 'Server for NFS' is now selected. Click Next.
  10. On the 'Select features' screen, select Next.
  11. On the 'Confirm installation selections' screen, select Install.
  12. On the 'Installation progress' screen, wait for the installation to complete then Close.

Create and Configure the Shared Folder

Next, you are going to create a folder to store data created by multiple qTest Sessions instances and use NFS to share the folder between instances.

  1. Open Fire Explorer and create a folder named "sessions-storage" in C:\ drive.
  2. Right-click on the sessions-storage folder and select Properties.
  3. On the 'sessions-storage Properties' windows, select the 'NFS Sharing' tab.
  4. Select the 'Manage NFS Sharing...' button.
  5. In the NFS Advanced Sharing widget, check the 'Share this folder' checkbox, then select Permissions.
  6. From the NFS Share Permissions screen, do the following:
    • Select 'Read-Write' option in the 'Type of access:' field
    • Select the checkbox 'Allow root access.'
  7. Select OK, then Close, to complete sharing the folder sessions-storage.

Configure Shared Server's Firewall

You need to configure the Firewall on the Shared Server to enable qTest Sessions to access the components you just installed. You need to open the ports of the following components:

  • PostgreSQL: the running port is 5432
  • NFS: the running port is 2049
  1. From the Control Panel, open Windows Firewall.
  2. Select Advanced settings.
  3. On the Windows Firewall with Advanced Security window, select Inbound Rules from the left panel.
  4. Select New Rule... in the Inbound Rules from the right panel.
  5. On the New Inbound Rule Wizard screen, select the option 'Port' and click Next.
  6. On the Protocol and Ports screen, do the following:
    • Select TCP option
    • Select Specific local ports option, and enter the port values of PostgreSQL and NFS, separate each value by a comma.
      Example: 5432, 2049.
    • Click Next when you are done.
  7. On the Action screen, make sure the option Allow the connection is selected, then click Next.
  8. In the Profile screen, make sure all the options for Domain, Private and Public are checked, then click Next.
  9. In Name screen, enter a name for your new rule, e.g. 'Shared Ports for qTest Sessions', then click Finish.
  10. You have finished setting up the Shared Server.

Important: You need to restart the server for the changes and configurations to take effect, then move on to Installing qTest Sessions on a separate server.

Install qTest Sessions on a Separate Server

First, log in to a Windows Server where you are going to install qTest Sessions.

Install NFS Client

Before you install qTest Sessions, you need to install the NFS client then use it to mount the shared folder 'sessions-storage', which we have set up in Shared Server, to a local drive. The local drive will be used to configure qTest Sessions when we install it.

  1. Open Server Manager, and navigate to the Dashboard.
  2.  Select Add Roles and Features.
  3. Click Next on the 'Before you begin' window.
  4. In Select installation type screen, make sure the option 'Role-based or feature-based installation' is selected, then click Next.
  5. On Select destination server screen, make sure the option 'Select server from the server pool' is selected, and click Next.
  6. In Select server roles screen, click Next.
  7. In Select features screen, select 'Client for NFS', then click Next.
  8. In Confirm installation selections, click Install.
  9. In Installation progress screen, wait for the installation to complete, and click Close.


Automatically Mount to the Shared Folder on the Shared Server when System Startups

Next step is to automatically mount the shared folder in Shared Server to a local drive when the server starts up.

Create a Script

  1. Create a batch file and put it in C:\mount.bat.
  2. Open the file in a text editor and enter the following command that mounts the sessions-storage folder in the shared server, whose IP address is, we set up in step #2 to a local drive name S:
    mount -o fileaccess=777 S:
  3. Save and close the file when you are done.

Create a Task to Execute the Batch File at System Startup

Next, you will create a task from the Task Scheduler that will execute our batch file at system startup.

  1. Open the Task Scheduler application and select Create Basic Task in the right panel.
  2. In Create a Basic Task screen, enter a name for our task, e.g. "Mount shared storage to S drive", then click Next.
  3. In Task Trigger screen, select option 'When the computer starts', then click Next.
  4. In Action screen, select the option Start a program and click Next.
  5. In Start a Program screen, enter 'C:\mount.bat' to Program/script field then click Next.
  6. In Summary screen, click Finish.

Edit the Task Properties

  1. From Task Scheduler, select Task Scheduler Library folder in the left panel.
  2. Look for your newly created task in the middle panel, and right click on it.
  3. Select Properties in the popup menu.
  4. In the Properties window, perform following actions:
    • Check the checkbox 'Run with highest privileges'
    • Click on 'Change User or Group...'
  5. In the Select User or Group window, do the following:
    • Enter 'system' to the field Enter the object to select
    • Select Check Names
    • Select OK 
  6. The property window now will look like below. Click OK to finish setting up the task property.

Restart Server

You will need to restart the server for the changes to take effect, then move on to downloading qTest Sessions.

Download qTest Sessions

  1. Download qtestctl from the link provided to you by our Implementation Team.
  2. Extract the downloaded file to C:\qtestctl
  3. To configure qTest Sessions, navigate to the extracted folder C:\qtestctl and open ‘qtest.config’ file.

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

Configure qTest Sessions

Configure Applications

Make sure there is sessions item in apps list, as shown below, in bold.

apps = ['sessions']

Configure Database

Configure Database in postgres section

      • postgres
        • host: Postgres server’s host name or ip address. We will use the IP address of the Shared Server where PostgreSQL is installed, which is
        • port: Postgres server’s port. We will use default port 5432
      • 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 {
// Postgres server’s host name or ip address.
// Here we will use the IP address of the Shared Server where PostgreSQL is installed,
// which is
    host = ''
    port = 5432
  auth {
      user = 'postgres'
      pass = 'root'   
  db {
      qtest = '[Enter database name of qTest Manager]'
      session = 'sessions'

Configure SSL

If you want to deploy qTest Sessions with SSL, navigate to section common in qTest.config file as shown below and replace blue text with actual values. Only information listed out here needs to be updated, other information should remain unchanged.

      • enable: set to true to enable secured connection (HTTPS) between 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 Sessions Server

In the qtest.config file, navigate to the section sessions to configure the qTest Sessions server.

      • port: configure server port that qTest Sessions will be listening
      • 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 the value of rootpath to reflect actual folder in the machine
        • type: type of the storage, a 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 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 the name 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:

sessions {
port: 9090
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
// if you prefer to use \ as path separator on Windows, make sure you use S:\\
rootpath = 'S:/'


Start qTest Sessions Server

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

Press Ctrl+C on Command Prompt to stop qTest Sessions.

Install qTest Sessions as a Windows Service

To enable qTest Sessions to automatically starts when Windows starts, you need to install it as a Windows service.

  1. Open a Command Prompt and navigate to the extracted folder C:\qtestctl
  2. Execute the command below in your Command Prompt window:
    C:\qtestctl> Install.bat
  3. You have successfully installed qTest Sessions on Windows.

Install 2nd Instance of qTest Sessions on another Windows Server

Repeat the download and configuration steps to install qTest Sessions on another server, whose IP address is

Setup qTest Sessions Load Balancer

Now you have installed two instances of qTest Sessions on two separate Windows servers with the following Private IP addresses:

      • qTest Sessions Server #1:
      • qTest Sessions Server #2:

Now, it's time to load balance.

You will need another Windows Server to install load balancing software. In our example, we will install and configure nginx on a Windows server whose public IP address is

Note: In this example, we use nginx to load balance qTest Sessions applications deployed on two Windows servers. However, you could choose to install your preferred load balancing software and follow the instructions of the software vendor to configure it.

Download nginx

  1. Access the Windows server where you will install nginx.
  2. Download nginx 1.13.0 here.
  3. Extract the downloaded nginx package to C:\nginx-1.13.0

Configure nginx

Open nginx configuration file at C:\nginx-1.13.0\conf\nginx.conf and edit the file as below (notice the highlighted configuration in bold).

Note: it is highly recommended that you copy and paste all of the content below to your nginx.conf file. If you installed qTest Sessions on servers that have different IP addresses from this example, you must change the IP addresses of those servers in the section upstream sessions_servers

#user nobody;
worker_processes 1;

#error_log logs/error.log;
#error_log logs/error.log notice;
#error_log logs/error.log info;

#pid logs/;

events {
worker_connections 1024;

http {
include mime.types;
default_type application/octet-stream;

#log_format main '$remote_addr - $remote_user [$time_local] "$request" '
# '$status $body_bytes_sent "$http_referer" '
# '"$http_user_agent" "$http_x_forwarded_for"';

#access_log logs/access.log main;

sendfile on;
#tcp_nopush on;

#keepalive_timeout 0;
keepalive_timeout 65;

#gzip on;

upstream sessions_servers {

server {
listen 80;
server_name localhost;

#charset koi8-r;
#access_log logs/host.access.log main;

location / {
proxy_pass http://sessions_servers;
proxy_redirect http://$http_host $scheme://$http_host;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $http_host;

Configure nginx to Start at Windows Start Up

Create a batch file that will start nginx when it is executed by following the steps below.

  1. Navigate to the folder C:\nginx-1.13.0\
  2. Create a file named startup.bat.
  3. Enter the following information in the file:
    start nginx.exe
  4. Save and close the file.
  5. Open Task Scheduler and select Create Basic Task in the Actions panel on the right.
  6. On the Create Basic Task screen, enter 'Start nginx' in the Name field then select Next.
  7. On the Task Trigger screen, select the option 'When the computer starts', then select Next.
  8. On the Action screen, select the option 'Start a program', then select Next.
  9. On the Start a Program screen, enter the following, then select Next:
    • Program/script: C:\nginx-1.13.0\startup.bat
    • Start in (optional): C:\nginx-1.13.0
  10. In the Summary screen, click Finish.
  11. You will be taken back to the Task Scheduler screen.
  12. Select Task Scheduler Library item in the left panel, in the middle panel locate the task you just created with the name 'Start nginx', right click and select Properties in the popup menu.
  13. From the Properties window, select Change User or Group...
  14. In Select User or Group window:
    • Enter system in the 'Enter the object name to select' field.
    • Select Check Names.
    • Select OK
  15. You will get back to the Properties window.
  16. Check the checkbox 'Run with highest privileges' then click OK.nginx-startup-task-scheduler-10.png
  17. You have finished setting up the load balancer with nginx and configured it to load balance the two qTest Sessions instances.

Now, restart the load balancing server and make sure it is up and running before proceeding to the next step.

Configure qTest Manager to Connect to qTest Sessions via a Load Balancer

  1. Login to your qTest Manager at URL using a site Administrator account.
  2. Open the Administration page.
  3. Select the System Configuration tab.
  4. In the Miscellaneous section, enter the URL for qTest Manager:
  5. In the QTEST EXPLORER | SESSIONS section, input the URL with the Public IP address of your qTest Sessions Load Balancer:
  6. Select Test Connection and wait for qTest Manager to show a message "Connected to the server successfully." Save.

Access qTest Sessions

Follow these steps to validate that qTest Sessions was installed and configured successfully.

  1. Select the nine box 9_box.png icon in qTest Manager's top navigation, to access qTest Sessions.
  2. In qTest Sessions homepage, select the + Session button to create a new Session.
  3. Enter Session's Title and select Save & Close.
  4. Verify that the Session you recently saved appears in the Query Result.
  5. You have successfully installed qTest Sessions on Windows.


Powered by Zendesk