Sessions 4.1 Load Balancer Installation Guide for Linux (non-Docker)

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 installing qTest Sessions 4.1 on load balancing environment.

Before you begin

  • Follow this article Getting Started with qTest OnPremise 9.0 - Spring 2018 to get an overview of qTest OnPremise deployment
  • qTest Sessions 4.1 only works with qTest Manager 9.0 or later
  • Your machines need to satisfy qTest's recommended hardware requirement
  • This instruction is specific for Ubuntu 16 environment, if you are using CentOS 7+, just replace apt-get command with yum. If your environment is different from Ubuntu 16 and/or CentOS 7, consult our customer support 

Diagram below demonstrates a sample scenario to deploy qTest Sessions in a load balancing environment:


qTest Manager: an instance of qTest Manager deployed in a CentOS/Ubuntu server that connects to a PostgreSQL database server

  • IPv4 Public IP:
  • Private IP:

qTest Manager DB Server: a PostgreSQL database server that manages qTest Manager database

  • IPv4 Public IP: we will not expose its IP address to the outside world
  • Private IP:

qTest Sessions Server #1: a server that host 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 acts as a load balancer for the two qTest Sessions servers. We will install and use HAProxy on this server for that purpose.

  • IPv4 Public IP:
  • Private IP:

Installation instruction

1. Install qTest Manager (Public IP address:

Select one of below instructions to install Manager 9.0:

After installed qTest Manager, note down its IPv4 Public IP address (or the Public IP address of the Manager's load balancer if you chose to install Manager on Load Balancing environment). This is the IP address that qTest Sessions application will access to it.

In our example, we will deploy qTest Manager on a server whose IP address is

2. Setup Shared Server (Private IP is

Access to the shared server and install following applications and/or packages

2.1 Install NFS (Network File Systems)

2.1.1 Update the repositories:

root@ip-[your-ip-address]:/home/ubuntu# sudo apt-get update

2.1.2 Install NFS server package by typing the command:

root@ip-[your-ip-address]:/home/ubuntu# sudo apt-get install nfs-kernel-server

2.1.3 Make directory you want to share with other computer. This is the directory being used to store data created by qTest Sessions Server application on other server:

root@ip-[your-ip-address]:/home/ubuntu# sudo mkdir /shared-sessions-storage

2.1.4 Edit /etc/exports config file

Here /etc/exports is the main config file for NFS. See the below examples and add share directories to the config file based on our requirement.

root@ip-[your-ip-address]:/home/ubuntu# vim /etc/exports

Add a line into /etc/exports file to make directory shared-sessions-storage can be access acrossed network.

#Share access to all networks
/shared-sessions-storage        *(rw,sync,no_root_squash)

Save and close the file when you are finished.

2.1.5 Start NFS service

root@ip-[your-ip-address]:/home/ubuntu# sudo /etc/init.d/nfs-kernel-server start

2.1.6 Check share status

root@ip-[your-ip-address]:/home/ubuntu# sudo exportfs -u
/shared-sessions-storage <world>

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

2.2.1 Access to your Shared Server then follow below instruction to install PostgreSQL 9.6.

# sudo add-apt-repository "deb $(lsb_release -sc)-pgdg main"
# sudo wget -q -O - | sudo apt-key add -
# sudo apt-get update
# sudo apt-get install postgresql-9.6

2.2.2 Verify PostgreSQL service is running with following command


# systemctl status postgresql


# systemctl status postgresql-9.6.service

If PostgreSQL is running, you'll see output that includes the text Active: active (exited). However, if you see Active: inactive (dead), start the PostgreSQL service using the following command (Ubuntu or CentOS):

# systemctl start postgresql

2.2.3 To enable PostgreSQL to start when system reboots, execute below command (either Ubuntu or CentOS):

# systemctl enable postgresql

2.2.4 Set password for postgres database user

In this guideline, we will use root as password for postgres user

# sudo -u postgres psql postgres
postgres=# \password
Enter new password: root
Enter it again: root
postgres=# \q

3. Create qTest Sessions database schema and name it sessions

# sudo -i -u postgres
postgres@ip-[your-ip-address]:~$ createdb sessions

Verify the sessions database has been created successfully

postgres@ip-[your-ip-address]:~$ psql
psql (9.5.7)
Type "help" for help.

postgres=# \l
                                  List of databases
   Name    |  Owner   | Encoding |   Collate   |    Ctype    |   Access privileges   
postgres  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
sessions  | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 |
template0 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
template1 | postgres | UTF8     | en_US.UTF-8 | en_US.UTF-8 | =c/postgres          +
           |          |          |             |             | postgres=CTc/postgres
(4 rows)

Quit psql and get back to terminal.

postgres=# \q
postgres@ip-[your-ip-address]:~$ exit

Now you have finished setting up Share Server. Next step is to install 2 qTest Sessions applications, each on its own server.

4. Install qTest Sessions

4.1 Install qTest Sessions Server #1 (Private IP address is

4.1.1 Access to Ubuntu server where you will install qTest Sessions

4.1.2 Open Terminal

4.1.3 Make sure you will perform all the installation steps as system user by executing following command:

root@ip-[your-ip-address]:/home/ubuntu# sudo su

4.1.4 Execute following command to update and upgrade system packages

root@ip-[your-ip-address]:/home/ubuntu# apt-get update -y && apt-get upgrade -y
root@ip-[your-ip-address]:/home/ubuntu# sudo apt-get install libfontconfig

4.1.5 Install and Configure NFS Client 

Enter following command to install NFS Client

root@ip-[your-ip-address]:/home/ubuntu# sudo apt-get install nfs-common rpcbind

Create a directory that will be used as qTest Sessions storage

root@ip-[your-ip-address]:/home/ubuntu# sudo mkdir /sessions-storage

Mount the shared directory in Shared Server (whose IP address is to the directory we just created

root@ip-[your-ip-address]:/home/ubuntu# sudo mount /sessions-storage

Edit the file /etc/fstab using vim

root@ip-[your-ip-address]:/home/ubuntu# vim /etc/fstab

... and add the following line to fstab file for permanent mount: /sessions-storage nfs rw,sync,hard,intr 0 0

Save and close the file when you are done.

Check the mounted share directory with mount command:

root@ip-[your-ip-address]:/home/ubuntu# mount
... on /sessions-storage type nfs4 (rw,relatime,vers=4.0,rsize=524288,wsize=524288,namlen=255,hard,proto=tcp,port=0,timeo=600,retrans=2,sec=sys,clientaddr=,local_lock=none,addr=[public IP Address])

Now whenever there are files being created/updated/deleted in sessions-storage directory by qTest Sessions, they will be also created/updated/deleted in the shared-sessions-storage directory in Shared Server and those files will be accessible by all qTest Sessions applications running on different servers.

4.1.6  Change to /usr/local directory, and start to download qtestctl package

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

# cd /usr/local

Extract qtestctl package and navigate to the extracted folder

/usr/local# tar xzvf qtestctl-linux-x64.tgz
/usr/local# cd qtestctl

4.1.7 Configure qTest Sessions

Edit qtest.config using following command:

/usr/local/qtestctl# vim qtest.config
Press insert to edit config file

Now you can start edit qtest.config file. If you are installing qTest Sessions on a separate server, make sure there is 'sessions' in apps list

apps = ['sessions'] If you are installing qTest Sessions on the same server with other qTest application(s), e.g. qTest Manager, append sessions to the app list.

apps = ['manager', 'sessions']

4.1.8 Configure databases

From qtest.config file, navigate to postgres section to configure qTest Sessions database.

  • host: PostgreSQL database server’s host name or ip address. In your example, it's the IP address of the Shared Server where PostgreSQL is installed:
  • port: PostgreSQL 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

Now the database configuration will look like below. Note: you should probably change the values in blue to reflect your environment configuration.

external {
  postgres {
    host = ''
    port = 5432
  auth {
      user = 'postgres'
      pass = 'root'   
  db {
      qtest = '[Database name of qTest Manager]'
      session = 'sessions'

4.1.9 Configure SSL

If you want to deploy qTest Sessions with SSL, navigate to section common in qTest.config file. 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

4.1.10 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
  • 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 blue.

sessions {
port: 9080
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/sessions-storage"

Press ESC and save the configuration with following command


4.1.11. Start qTest Sessions 

/usr/local/qtestctl# ./qtestctl start

4.1.12 Install qtest service

To enable qTest Sessions to automatically start when OS starts, we need to install qtest service.

On Terminal, press Ctrl + C to stop qtestctl if it is running.

Note: If you install qTest Sessions in the same machine with other qTest application(s), you only need to execute below command once and only once when you finished installing ALL the applications in this server. Refer to this article to learn more about installing qtest service.

Execute below command to install qtestctl as a service.

/usr/local/qtestctl# ./install

Verify qtest service has been successfully installed and running with following command

/usr/local/qtestctl# 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

4.2 Install qTest Sessions Server #2 (Private IP address is

Repeat step #4.1.1 to #4.1.12 to install qTest Sessions on server #2

4.3 Install qTest Sessions Load Balancer (Public IP address is

Follow below instructions to install qTest Sessions Load Balancer.

4.3.1 Install HAProxy

Open Terminal and enter following command to install HAProxy

$ sudo su
root@ip-[your-ip-address]:# apt-get install haproxy

Edit /etc/default/haproxy to enable HAProxy to be started by the init script.

root@ip-[your-ip-address]:/usr/local# vim /etc/default/haproxy

Set ENABLED option to 1


Save and close the file when you are finished.

To check if this change is done properly execute the init script of HAProxy without any parameters. You should see the following.

root@ip-[your-ip-address]:~# service haproxy
Usage: /etc/init.d/haproxy {start|stop|reload|restart|status}

4.3.2 Configure HAProxy to load balance qTest Sessions installed on Server #1 (Private IP is and Server #2 (Private IP is by editing the file /etc/haproxy/haproxy.cfg with vim 

root@ip-[your-ip-address]:~# vim /etc/haproxy/haproxy.cfg

Update the file as following, note the values in bold are important configurations and red ones are information that need attention. Other default configurations should be kept unchanged.

        log /dev/log    local0
        log /dev/log    local1 notice
        chroot /var/lib/haproxy
        stats socket /run/haproxy/admin.sock mode 660 level admin
        stats timeout 30s
        user haproxy
        group haproxy

        # Default SSL material locations
        ca-base /etc/ssl/certs
        crt-base /etc/ssl/private

        # Default ciphers to use on SSL-enabled listening sockets.
        # For more information, see ciphers(1SSL). This list is from:
        ssl-default-bind-options no-sslv3

        log     global
        mode    http
        option  httplog
        option  dontlognull
        timeout connect 5000
        timeout client  50000
        timeout server  50000
        errorfile 400 /etc/haproxy/errors/400.http
        errorfile 403 /etc/haproxy/errors/403.http
        errorfile 408 /etc/haproxy/errors/408.http
        errorfile 500 /etc/haproxy/errors/500.http
        errorfile 502 /etc/haproxy/errors/502.http
        errorfile 503 /etc/haproxy/errors/503.http
        errorfile 504 /etc/haproxy/errors/504.http

frontend http_front
   bind *:80
   mode http
   stats uri /haproxy?stats
   default_backend http_back # this will refer to a backend section whose name is `http_back`

backend http_back # here we name the backend as `http_back`
   mode http
   balance roundrobin
# We name qTest Sessions Server #1 and #2 as `sessions1` and `sessions2`,
# however you can name it whatever you want.
# The other important configuration is the IP addresses and ports of the two qTest Sessions server

# we need to enter correctly
   server sessions1 check
   server sessions2 check

Save and close the file when you're done

4.3.3 Verify the Load Balancer status:

Open web browser and navigate to this URL, where is the public IP address of the Load Balancer. If everything is OK, you'll see the result as below screenshot:


5. Configure qTest Manager

5.1 Login to your qTest Manager using a site Administrator account and open Administration page


5.2 Click on the tab SYSTEM CONFIGURATIONS

5.3 In MISCELLANEOUS section, enter URL of qTest Manager to qTest server's domain field:

  • http://[qTest_Manager_IPAddress]:[Port] if you install qTest Manager without SSL
  • Or https://[qTest_Manager_IPAddress]:[Port] if you installed qTest Manager with SSL certificate.


5.4 In the QTEST EXPLORER | SESSIONS section, input the URL of your qTest Sessions site, which is the public IP Address of qTest Sessions Load Balancer


5.5 Click Test Connection and wait for qTest Manager to show a message "Connected to server successfully" then click Save to save the configuration.

5.6 Go back to qTest Manager home page, access to qTest Sessions from nine box icon


5.7 In qTest Sessions home page, click `+ Session` button


5.8 In Create Session screen, enter session title as 'Test Session' then click Save & Close button.


5.9 If everything is OK, the session will be created and shown in qTest Sessions home page.


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

Powered by Zendesk