Sessions 4.1 Single Server Installation Guide for Linux (non Docker)


In this article, we provide step-by-step instructions to install qTest Sessions 4.1 on a CentOS or Ubuntu machine. Please read the instructions thoroughly before starting your installations.

To request assistance with installation or obtain the self-installation links, complete the OnPremise New Install Form.

Note: If you are not performing a fresh install and are upgrading, use the Upgrade Request Form and reference the OnPremise Upgrades Guide.

Before You Begin

  • qTest Sessions 4.1 only works with qTest Manager 9.0 or later.
  • You need to install qTest Manager before installing qTest Sessions.

Read the following:

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 the Terminal.
  2. Ensure you perform all the installation steps as a System User by executing the following command:
    # sudo su
  3. Execute the 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 

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. 

Access 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


# yum install -y 
# yum install postgresql96-server -y
# /usr/pgsql-9.6/bin/postgresql96-setup initdb
# systemctl enable postgresql-9.6.service
# systemctl start postgresql-9.6.service

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

To enable PostgreSQL to start when system reboots, execute below command (either 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

Create Sessions Database

Create sessions database schema by postgres user 

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

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

Download qtestctl 


  • If you are installing qTest Sessions in the same server with other qTest application, e.g. qTest Manager, then you do not need to re-download this installation package but use the one you have downloaded when you installed qTest Manager. Otherwise, if you plan to install qTest Sessions on a separate server, follow steps below to download qTest Sessions
  • To learn more about qtestctl, refer to this article qTest OnPremise - Technical detail about qtestctl

Change to /usr/local directory, and start to download qTest Sessions.

# cd /usr/local
/usr/local # wget <ENTER DOWNLOAD LINK HERE>

Extract qtestctl package and navigate to the extracted folder.

/usr/local# tar xzvf <DOWNLOADED PACKAGE FILE NAME>
/usr/local# cd qtestctl

Configure qTest Sessions

Assume that qtestctl package was extracted at /usr/local/qtestctl. Now, navigate to that folder and open the qtest.config file using following command:


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


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

Now you can start edit qtest.config file.

Configure Applications

11.1.1 If you are installing qTest Session in a separate server, make sure there is sessions item in apps list, as show below.

apps = ['sessions']

11.1.2 If you are installing qTest Sessions on the same server with other qTest application(s), e.g. qTest Manager, make sure you append sessions to the app list.

apps = ['manager', 'sessions']

Configure qTest Sessions Databases

Navigate to external section in qtest.config file as shown below and replace blue text with actual values. Only information listed out here needs to be updated, other information should remain unchanged.

external {
  postgres {
    host = '[PostgreSQL server's IP or hostname]'
    port = [PostgreSQL server's port number]
  auth {
      user = '[PostgreSQL username]'
      pass = '[PostgreSQL user password]'
  db {
      qtest = '[Database name of qTest Manager]'
      session = 'sessions'

Configure SSL

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

Configure qTest Sessions

From qtest.config file, navigate to section sessions as shown below to configure qTest Sessions application. Replace blue text with actual values. Only information listed out here needs to be updated, other information should remain unchanged.

sessions {
port: [qTest Sessions running port]
qtest {
host = '[http or https]://[qTest Manager server's IP or hostname]:[HTTP port]'
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 = "/path/to/sessions/resources"

Press ESC and save the configuration with following command


Start qTest Sessions 

# ./qtestctl start

Configure qTest Manager to connect to qTest Sessions

13.1 Login to your qTest Manager using a Site Administrator account

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

13.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 certificate
  • Or https://[qTest_Manager_IPAddress]:[Port] if you installed qTest Manager with SSL certificate.


13.4 In QTEST EXPLORER | SESSIONS section, input the URL of your qTest Sessions server to qTest Explorer | Sessions URL field:

  • http://[qTest_Sessions_IP_Address]:[HTTP_Port] if you install qTest Sessions without SSL certificate
  • Or https://[qTest_Sessions_IP_Address]:[HTTP_port] if you installed qTest Sessions with SSL certificate.


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

Access qTest Sessions


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.


Install qTest Service

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

15.1 In the Terminal, press `Ctl + C` if qtestctl is running

15.2 Execute below command to install qtest service

Note: if you install qTest Sessions in the same server with other qTest applications, e.g. qTest Manager, you only need to execute below command once.

/usr/local/qtestctl# ./install

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

Next Steps

Powered by Zendesk