Sessions 4.0.2 Single Server 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 guide, we will run you through step by step to install qTest Sessions v4.0.2 on a separated CentOS/Ubuntu machine and then connect to qTest Manager 8.7.3+ 


  • qTest Sessions v4.0.2 only works with qTest Manager v8.7.3 or later
  • This guideline is verified on CentOS 7+ and/or Ubuntu 16. If you are using other CentOS/Ubuntu version, please contact our Customer Support.

Before you begin

Install qTest Sessions

Most of the installation steps are performed on Terminal. It is highly recommended that you copy and paste the command/scripts to your Terminal and execute it.

1. Open Terminal

2. Make sure you perform all the installation steps as system user by executing following command

# sudo su

3 .Execute following command to update and upgrade system packages


# apt-get update -y && apt-get upgrade -y
# apt-get install libfontconfig


# yum check-update && yum update 

4. Install PostgreSQL 9.5


# sudo sh -c 'echo "deb xenial-pgdg main 9.5" >> /etc/apt/sources.list.d/pgdg.list'
# sudo wget -q -O - | sudo apt-key add -
# sudo apt-get update
# sudo apt-get install -y postgresql-9.5


# yum install -y
# yum install postgresql95-server postgresql95 –y
# /usr/pgsql-9.5/bin/postgresql95-setup initdb
# systemctl start postgresql-9.5.service
# systemctl enable postgresql-9.5.service

5. Verify PostgreSQL service is running with following command


# systemctl status postgresql


# systemctl status postgresql-9.5.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

To enable PostgreSQL to start on reboot, execute below command (Ubuntu or CentOS):

# systemctl enable postgresql

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

7. Create sessions database schema by postgres user 

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

8. Verify the database has been created successfully with following commands

postgres@ip-[your-ip-address]:~$ psql
postgres@ip-[your-ip-address]:~$ \l

The result would look like below showing the created sessions database


9. Quit PostgreSQL command prompt and logout postgres user

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

10. Install Java 8


# cd /home/ubuntu
root@ip-[your-ip-address]:/home/ubuntu# add-apt-repository ppa:webupd8team/java
root@ip-[your-ip-address]:/home/ubuntu# apt-get update -y
root@ip-[your-ip-address]:/home/ubuntu# apt-get install oracle-java8-installer


# yum install wget
# cd /opt/
# wget --no-cookies --no-check-certificate --header "Cookie:; oraclelicense=accept-securebackup-cookie"
# cd /opt/jdk1.8.0_131/
# alternatives --install /usr/bin/java java /opt/jdk1.8.0_131/bin/java 2
# alternatives --config java 

Note: The installer will ask for your confirmation to install Java components. Just answer 'Y', 'Ok' or 'Yes' where applicable.

Verify Java has been installed successfully.

# java -version
java version "1.8.0_131"

Java(TM) SE Runtime Environment (build 1.8.0_131-b11)
Java HotSpot(TM) 64-Bit Server VM (build 25.131-b11, mixed mode) 

11. Download qtestctl 

Change to /usr/local directory, and start to download qtesctl

# cd /usr/local

Extract qtestctl package and navigate to the extracted folder

# cd qtestctl

12. Configure qtestctl

Edit qtest.config using following command:


# vim qtest.config
Press insert to edit config file


# vi qtest.config
Press insert to edit config file

Now you can start edit qtest.config file.

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

apps = ['sessions']

12.2 Configure databases in postgres section

  • host: postgres database server’s host name or ip address
  • port: postgres 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
external {
  postgres {
    host = 'localhost'
    port = 5432
  auth {
      user = 'postgres'
      pass = 'root'   
  db {
      qtest = 'qtest'
      session = 'sessions'

12.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. Only affected if enabled field is set to true
    • cert: absolute path to .cert file. Only affected if enable is set to true
  • 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 bold.

sessions {
port: 9443
ssl {
enabled = false
key = "/absolute/path/to/dist/ssl/server.key"
cert = "/absolute/path/to/dist/ssl/server.crt"
qtest {
host = "http://localhost:8080"
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/session-resources"

Press ESC and save the configuration with following command


13. Initialize qTest Sessions database and seed data

Make sure qtestctl has 'execute' permission by enter following command

# sudo chmod +x qtestctl

Next, enter following command to initialize database:

# ./qtestctl sessions:initdb

If you encounter error /usr/bin/env: ‘sh\r’: No such file or directory. Run below commands then re-run the above commands again.

# sudo apt install dos2unix
# dos2unix qtestctl

14. Start qTest Sessions 

# ./qtestctl sessions:start

15. Configure qTest Manager to connect to qTest Sessions

15.1 Login to your qTest Manager using a Site Administrator account

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

15.3 In QTEST EXPLORER | SESSIONS section, enter URL of your qTest Sessions site, following this convention: [scheme]://[qTest Sessions IP Address]:[Port]:

  • scheme: if you install qTest Session with SSL certificate, enter https, otherwise, enter http
  • qTest Sessions IP Address: enter the IP address where qTest Sessions is installed
  • Port: enter port number that qTest Sessions will be listening. Refer to previous section `12.3 Configure Sessions server` for the configured port number

In our example, qTest Session URL will look like below:


15.4 Click Save button for the changes to take affect.

16. Access to qTest Sessions from qTest Manager and validate the installation

From qTest Manager home page, access to qTest Sessions from nine box icon.


From qTest Sessions home page, click + Sesisons to create a new session


Enter Session's Title and click Save & Close.


Verify that the new session has been created successfully.


17. Install qtest service

To enable qTest Sessions to automatically starts on system startup, we need to install qtest as a service.

17.1 In the Terminal, press `ctl + c` if qtestctl is running

17.2 Execute below command to install qtest service

> ./install

17.3 Verify that the service has been successfully installed with following command

> systemctl status qtest

If the installation was successful, you will see output that includes the text like below

qTest has successfully started!

However, if you see:

Active: inactive (dead)

then enter following command to start the service

> systemctl start qtest

You have finished installing qTest Sessions on Linux (non Docker) environment.

Subscribe To Our Blog
Powered by Zendesk