Sessions 4.0.2 Single Server 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 guide, we will walk you through step by step to install qTest Sessions v4.0.2 on a separated Windows machine. Please go through the guide below thoroughly before starting your installations.

IMPORTANT: qTest Sessions v4.0.2 only works with qTest Manager v8.7.3 or later

Before you begin

Install prerequisite packages

Prerequisite packages must be installed and running prior to qTest Sessions installation.

1. Install and Configure 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 the 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:postgresql-service-status.png

After installing PostgreSQL, you need to enable remote access to PostgreSQL database server by doing following steps:

  • Open file C:\Program Files\PostgreSQL\9.5\data\pg_hba.conf. Look for the following line and if it does not exit, append the below line to the file.
    host all all [POSTGRES_SERVER_IP_ADDRESS]/32 md5
    • Note: [POSTGRES_SERVER_IP_ADDRESS] is the IP address of the machine that PostgresSQL is installed
  • Open file C:\Program Files\PostgreSQL\9.5\data\postgresql.conf. Look for the following line, and if it does not exist, append it to the file:
    listen_addresses = '*'

2. Create qTest Sessions Database

After PostgreSQL has been successfully installed and configured, you will need to create a database schema. It will be used when installing qTest Sessions.

  • Open Command Prompt on your machine. Change the current path to PostgreSQL installation directory:
    > cd C:\Program Files\PostgreSQL\9.5\bin
  • Create a database schema using the command below:
    C:\Program Files\PostgreSQL\9.5\bin>createdb -h [YOUR_POSTGRES_SERVER_IP_ADDRESS] -p [YOUR_POSTGRES_SERVER_PORT] -U postgres -W [YOUR_DATABASE_NAME]
    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: [POSTGRES_PASSWORD] //enter 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: //enter your password here
    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 if the above one has been successfully created:
    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)
    sessions database has been created and listed.
  • Quit psql program.
    postgres-# \q

3. Install Java 8

Download and install Java 8 from this link:

Install and Configure qTest Sessions

1. Install qTest Sessions

1.1. Download qtestctl at <DOWNLOAD LINK>

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

1.3. Configure qTest Sessions

Navigate to the extracted folder C:\qtestctl\ then open qtest.config file in your favorite text editor to configure qTest Sessions.

1.3.1. Configure applications: make sure there is 'sessions' in apps list

apps = ['sessions']

1.3.2. Configure database by entering these values to external section in qtest.config file

  • 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

Below is an example of database configuration for qTest Sessions, in bold.

external {
postgres {
host = 'localhost'
port = '5432'
auth {
user = 'postgres'
pass = 'root'
db {
qtest = 'qtest'
session = 'sessions'

1.3.3. 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
    • 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" // only affected when enabled is set to true
cert = "/absolute/path/to/dist/ssl/server.crt" // only affected when enabled is set to true
qtest {
host = 'http://localhost:8080'
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:\\resources'

1.3.4. Create qTest Sessions database and seed data

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

Enter below command to the command prompt

C:\qtestctl>qtestctl sessions:initdb

1.3.5. Start qTest Sessions

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

2. 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 folder 'qtestctl’

Execute below command in your command prompt:

C:\qtestctl>net start qtest


3. Configure qTest Manager to connect to qTest Sessions

3.1 Login to your qTest Manager using a Site Administrator account.

3.2 Click into the Site Administration page then click on the tab SYSTEM CONFIGURATIONS.

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


3.4 In QTEST EXPLORER | SESSIONS section, input the URL of your qTest Sessions server, such as http://[qTest_Sessions_IP_Address]:[HTTP_Port] or https://[qTest_Sessions_IP_Address]:[HTTP_port] if you installed qTest Sessions with SSL certificate.


3.5 Click Save button.

4. Access to qTest Sessions

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

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


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


4.3 Enter Session's Title and click Save & Close


4.4 Verify that the Session you have recently saved appears in the Query Result 


You have successfully installed qTest Sessions on Windows.

Powered by Zendesk