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

For qTest Premium and Elite editions, you will need to install qTest Manager before installing qTest Sessions
Before proceeding, please make sure qTest Manager is running and your qTest license file has been imported. If not, go to Manager 8.7.3 Single Server Installation Guide for Windows for instructions to install and run qTest Manager.
Please make sure your server environment meets recommended hardware requirements

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:

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 192.168.74.77 -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 192.168.74.77 -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: http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

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

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