Sessions 4.0.2 Load Balancer Installation Guide for Windows

To request installation assistance or to obtain the links to self-install, please click here to fill out the New Install Form.

In this article, we'll run you through a sample scenario to install qTest Sessions 4.0.2 on different Windows server machines with a Load Balancer, then connect it to qTest Manager on another machine.

Before you begin 

Before you install qTest Sessions, make sure following things:

  • Your machines need to satisfy qTest's recommended hardware requirements
  • qTest Sessions 4.0.2 only works with qTest Manager 8.7.3 and later
  • 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

Install qTest Sessions with Load Balancer


Screenshot 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

  • IPv4 Public IP:
  • qTest URL:

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:

Installation instructions

1. Install qTest Manager

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

After 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

2. Setup Shared Server

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


2.1 Install and Configure PostgreSQL 9.5

2.1.1 Install PostgreSQL 9.5

qTest Sessions requires PostgreSQL 9.5 that you can download it here. After downloading, double click on the downloaded file and follow the installation wizard to install it.

When installation completes, verify that the PostgreSQL service is running by following below steps:

  • Open command prompt and type services.msc to open Services window 
  • On Services window, look for a service named postgresql-x64-9.5 and make sure its Status is Running and its Startup Type is set to Automatic, as shown in below screenshot:


2.1.2 Configure PostgreSQL 9.5

After installing PostgreSQL, you need to enable remote access to PostgreSQL database server.

Open file C:\Program Files\PostgreSQL\9.5\data\pg_hba.conf. 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

Your C:\Program Files\PostgreSQL\9.5\data\pg_hba.conf now will look like below:


Next, open file C:\Program Files\PostgreSQL\9.5\data\postgresql.conf. Look for the following line, and if it does not exit, append it to the file:

listen_addresses = '*'

Save and close the file when you have finished.

You need to restart PostgreSQL service for the changes to take effect.

Open command prompt and type services.msc to open Services window 

On Services window, look for the service named postgresql-x64-9.5, right click on it and select Restart in the popup menu. As below screenshot:


Important note:

  • By default, PostgreSQL runs on port 5432. We will configure firewall for this later.

2.1.3 Create qTest Sessions database

After PostgreSQL has been successfully installed and configured, you will need to create a database schema for qTest Sessions.

Open the console on your machine. Change the current path to PostgreSQL installation directory:

C:\Users\SampleUser>cd C:\Program Files\PostgreSQL\9.5\bin

Create a database schema using the command below:


For example:

C:\Program Files\PostgreSQL\9.5\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 user postgres

Connect to the database:

C:\Program Files\PostgreSQL\9.5\bin>psql -h -U postgres -W sessions
Password for user postgres: root // again, we will use `root` as the password of user postgres
psql (9.5.6)
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.

List out existing schema to verify sessions database schema has been successfully created, as show below, in bold:

postgres=# \l
                          List of databases
 Name             |  Owner   | Encoding |          Collate           |
 Ctype            |   Access privileges
 postgres         | postgres | UTF8     | English_United States.1252 | English_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)

Quit psql program.

postgres-# \q


2.2 Install and Configure NFS

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

2.2.1 Install NFS

Open Server Manager, navigate to Dashboard then click on Add Roles and Features.


Click Next on the 'Before you begin' window.


In Select installation type screen, make sure the option 'Role-based or feature-based installation' is selected, then click Next.


On Select destination server screen, make sure the option 'Select server from the server pool' is selected, and click Next.


From 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)', then click on the checkbox before the item 'Server for NFS'


Next, Click on 'Add Features' in the popup.


The 'Server for NFS' is now selected. Click Next.


In 'Select features' screen, click Next.


In 'Confirmation installation selections' screen, click Install.


In 'Installation progress' screen, wait for the installation completes then click Close.


2.2.2 Create and configure shared folder

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

Open Fire Explorer and create a folder named "sessions-storage" in C:\ drive. 

Right click on sessions-storage folder and select Properties. On 'sessions-storage Properties' windows, select 'NFS Sharing' tab then click on 'Manage NFS Sharing...' button.


In the opening NFS Advanced Sharing window, check the checkbox 'Share this folder', then click on Permissions button.


From NFS Share Permissions screen, do the following:

  • Select 'Read-Write' option in the 'Type of access:' field
  • Check the checkbox 'Allow root access'
  • Click 'OK' button


Click OK, then Close, to complete sharing the folder sessions-storage.

2.3 Configure Shared Server's Firewall

We need to configure Firewall on the Shared Server to enable qTest Sessions to access to the components we just installed. What we are going to do is to open the ports of the following components:

  • PostgreSQL: the running port is 5432
  • NFS: the running port is 2049

Go to Control Panel and open Windows Firewall then click on Advanced settings.


On Windows Firewall with Advanced Security window, select Inbound Rules from the left panel, then click on New Rule... in the Inbound Rules from the right panel


In New Inbound Rule Wizard screen, select option 'Port' and click Next.


In 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. For example: 5432, 2049.
  • Click Next when you are done.


In Action screen, make sure the option Allow the connection is selected, then click Next.


In the Profile screen, make sure all the options for Domain, Private and Public are checked, then click Next.


In Name screen, enter a name for your new rule, e.g. 'Shared Ports for qTest Sessions', then click Finish.


You have finished setting up the Shared Server.

You need to restart the server for the changes and configurations to take effect, then move on to the next step.

3. Install qTest Sessions in a separated server

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

3.1 Install NFS client

Before install qTest Sessions, we need to install NFS client then use it to mount the shared folder 'sessions-storage' that 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.

Follow these steps to install NFS client.

First, open Server Manager, navigate to Dashboard then click on Add Roles and Features.


Click Next on the 'Before you begin' window.


In Select installation type screen, make sure the option 'Role-based or feature-based installation' is selected, then click Next.


On Select destination server screen, make sure the option 'Select server from the server pool' is selected, and click Next.


In Select server roles screen, click Next.


In Select features screen, select 'Client for NFS', then click Next.


In Confirm installation selections, click Install.


In Installation progress screen, wait for the installation to complete, and click Close.


3.2 Automatically mount to shared folder on Shared Server when system startups

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

3.2.1 Create a script

First, create a batch file and put it at C:\mount.bat. Open the file in a text editor and enter following command that mount 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:

Save and close the file when you are done.

3.2.2 Next, we will create a task from Task Scheduler that will execute our batch file at system start up.

Open Task Scheduler application and click on Create Basic Task in the right panel.


In Create a Basic Task screen, enter a name for our task, e.g. "Mount shared storage to S drive", then click Next.


In Task Trigger screen, select option 'When the computer starts', then click Next.


In Action screen, select the option Start a program and click Next.


In Start a Program screen, enter 'C:\mount.bat' to Program/script field then click Next.


In Summary screen, click Finish.


Next, we will edit the task properties.

From Task Scheduler, select Task Scheduler Library folder in the left panel.

Look for our newly created task in the middle panel. When you found it, right click on it and select 'Properties' in the popup menu.


In the Properties window, perform following actions:

  • Check the checkbox 'Run with highest privileges'
  • Click on 'Change User or Group...'


In Select User or Group window, do the following:

  • Enter 'system' to the field Enter the object to select
  • Click on Check Names button
  • Click OK button


The property window now will look like below. Click OK to finish setting up the task property.


3.3 Restart Server

We need to restart the server for the changes to take effect, then move on with next step.

4. Install and Configure qTest Sessions

Download qtestctl: <DOWNLOAD LINK HERE>

Extract downloaded file to C:\qtestctl

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

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

apps = ['sessions']

4.2 Configure database in postgres section

  • 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'

4.3 Configure 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:

sessions {
port: 9090
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 = 'S:\'


4.4 Create qTest Sessions database and seed data

Open command prompt, navigate to extracted folder C:\qtestctl and enter below command to create sessions database as well populate initial data.

C:\qtestctl> qtestctl sessions:initdb

4.5 Start qTest Sessions server

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

4.5 Install qTest Sessions as a Windows service

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> Install.bat
C:\qtestctl> net start qtest

You have successfully installed qTest Sessions on Windows.

5. Install 2nd instance of qTest Sessions on another Windows server

Repeat step #4 to install qTest Sessions on another server whose IP address is

6. Setup a load balancer to load balance qTest Sessions

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

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

It's time to load balance it.

We will need another Windows Server to install a 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.

6.1 Download nginx

Access to the Windows server where we will install nginx.

Download nginx 1.13.0 here.

Extract the downloaded nginx package to C:\nginx-1.13.0

6.2 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).

Notes: it is highly recommended that you copy and paste all of below content to your nginx.conf file. If you installed qTest Sessions on servers that have different IP addresses with 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;

6.3 Make nginx start at Windows starts up

6.3.1 Create a batch file that, when executed, will start nginx by following below steps

Go to folder C:\nginx-1.13.0\ and create a file named startup.bat, then enter following information to the file:

start nginx.exe

Save and close the file.

Open Task Scheduler and click on Create Basic Task in the right panel


In Create Basic Task screen, enter 'Start nginx' to the Name field then click Next.


In Task Trigger screen, select option 'When the computer starts', then click Next.


In Action screen, select the option 'Start a program', then click Next.


In Start a Program screen, enter the following to the relevant fields, then click Next:

  • Program/script: C:\nginx-1.13.0\startup.bat
  • Start in (optional): C:\nginx-1.13.0


In the Summary screen, click Finish.


You will be back to Task Scheduler screen.

Select Task Scheduler Library item in the left panel, locate the task we just created with the name 'Start nginx' in the middle panel, right click on it and select Properties in the popup menu.


From the Properties window, click on Change User or Group...


In Select User or Group window:

  • Enter system to the 'Enter the object name to select' field
  • Click Check Names button
  • Click OK


You will get back to the Properties window.

Now check the check box 'Run with highest privileges' then click OK.


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.

7. Configure qTest Manager to connect to qTest Sessions via load balancer

7.1 Login to your qTest Manager application at URL using a Site Administrator account

7.2 Go to the Site Administration page and click on the tab SYSTEM CONFIGURATIONS

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


7.4 In the QTEST EXPLORER | SESSIONS section, input the URL with the Public IP address of your qTest Sessions Load Balancer:


7.5 Click on Save button.

7.6 From qTest Manager's top navigation, access to qTest Sessions


You will notice that qTest Manager now can access to qTest Sessions applications via the load balancer, as below screenshot.


In qTest Sessions home page, click + Session button to create a new Session


In Create Session page, enter Session's Title and click Save & Close


Verify that the Session you have recently saved appears in the home page.


You have successfully installed qTest Sessions on Windows load balancing environment.


Powered by Zendesk