2025.8 OnPremises Single Server Installation Guide for Windows

In this article, we provide instructions to install qTest components for 2025.8 OnPremises to a single Windows machine. Please read the instructions thoroughly before starting your installations.

Complete the OnPremises Technical Services Request form (opens in new tab) to request assistance or obtain self-installation links, whether you're upgrading or performing a fresh install.

About the Command Line Wizard

The qTest 2025.8 Command Line Wizard is a command line interface application that allows you to configure basic settings for qTest applications in your purchase package.

You should understand these Command Line Wizard characteristics before you begin:

  • For each step, the installer will prompt you for a specific input value. After you provide a value, the installer will validate the input. If the value is incorrect, or additional permissions are required, an explicit error message displays so it’s easy to know how the input value should be corrected.

    • Default values display in square brackets [ ]. To use the default value, simply hit the Enter key.

    • Input values for yes/no questions, should be 'y', 'yes','n', 'no' (ignore case sensitive.) Any value other than those listed will be treated as a 'no.'

  • To terminate the configuration at any time without completing it, press Ctrl+C.

    In the event, you cannot start the Command Line Wizard again after terminating the configuration, backup then remove the qTest.config file. Try to start the Command Line Wizard again.

Before You Begin

Read the following:

Please note that the Command Line Wizard will prompt you for each installation instruction. You will need to perform action items and gather specific connection information before you begin the installation process. Use the application checklist below to ensure you have all the required values readily available.

TLS Connections

Beginning with qTest 2025.8, client connections for qTest and PostgreSQL will be configured to use transport layer security (TLS) by default. However, the option to use non-TLS (HTTP) connections is still available at your own risk. A self-signed certificate is provided for convenience, but Tricentis recommends a CA-signed certificate whenever possible.

Ports

Open the Ports for the prerequisite applications and qTest applications you are installing prior to any self-assisted installation or upgrade. You should only open the HTTPS ports if you plan to serve SSL from the application.

Prerequisite Applications

Product

Port

Transport Protocol

Application Protocol

Source

Destination

Configurable

PostgreSQL

5432

TCP

TCP

qTest Manager, Insights, Sessions, Parameters

Database (PostgreSQL) Server

Yes

Elasticsearch 

9200 (TCP)

9300 (if using ES Clustering)

TCP

HTTP

qTest Manager

Database (Elasticsearch) Server

Yes

Network File System (NFSV4)

2049

TCP/UDP

TCP/UDP

qTest Manager, Sessions

NFS

No

Native Linux and Windows

Product

HTTPS Port

HTTP Port

Transport Protocol

Application Protocol

Source

Destination

Configurable

Manager/API

443 

80

TCP

HTTPS

Web Browser, API

qTest Manager Application Server/API Server

Yes

Sessions

8443

8080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Scenario

6443

6080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Insights

9443

9080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Parameters

5443

5080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Pulse

4443

4080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Launch

3443

3080

TCP

HTTPS

Web Browser, API

qTest Application Server

Yes

Please note that we strongly recommend that you use the HTTPS ports in your setup.

Suggested application ports are listed above. However, you are allowed to use a port of your choosing for the qTest applications you install.

Application Checklist

You will need to gather the following information for each application prior to beginning the installation and configuration.

PostgreSQL 16.x - Must be installed and configured prior to qTest application installation.

TLS Configuration

  • qTest and PostgreSQL

    • Cipher suite - the list of cipher suites the program uses in the ssl_ciphers.config file.

      • The server uses a default set of cipher suites in the ssl_ciphers.config file, but you can edit the configuration file to provide your own. The configuration file contains cipher format examples and details on how to provide your own ciphers.

    • Certificate Authority (CA) Signed Certificate –Will be inserted into the qTest Java Keystore. Use PKCS #8 format. May be signed by an internal CA. Must have a fully qualified domain name and resolvable DNS alias, with valid creation and expiration dates. Use the absolute path to certificate location on the server. The user executing the qtestctl installation must also have read permission for this file and path recursively.

    • Private Key - Use the absolute path to certificate location on the server. The user executing the qtestctl installation should also have read permission for this file and path recursively. If a passphrase is used for the private key, make sure to have it available.

This information is only needed if you will be deploying with an SSL secured connection:

qTest Applications

  • Certificate File (.crt) - absolute path to the certificate file on this server.

    • Location should not be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation must also have read permission for this file and path recursively.

  • Private Key (.key) - absolute path to the private key file on this server.

    • Location should not be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation must also have read permission for this file and path recursively.

  • Private Key passphrase

qTest Applications

  • Manager

    • Port to be used for communications (HTTP or HTTPS)

    • Local Disk directory for attachment storage – Location should not be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation should also have read permission for this file and path recursively.

      - OR -

      Amazon (AWS) S3 for attachment storage - Requires bucket name, access key, region, and secret key. For a procedure on setting up AWS S3 for attachment storage, refer to Create an AWS S3 Bucket for qTest Attachment Storage.

    • Directory to logging storage - Location should not be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation should also have read permission for this file and path recursively.

    • Fully Qualified Domain Name, Hostname, or IP Address to construct the application URL – This must be resolvable outside of the server.

    • Secret key – You can generate the first key from the installation wizard. After you generate a secret key, make sure you save and use the same key for all of your qTest applications, on all instances.

    • Integration secret key – You can generate the first key from the installation wizard when you install qtestctl. After you generate a secret key, make sure you save this key in a safe place. You must use the same key for all nodes that run Manager or Launch during installation and upgrades.

  • Sessions

    • Port to be used for communications (HTTP or HTTPS)

    • Storage type and location for resource files

      • Disk storage – Local disk, NFS, or NAS

      • Amazon S3 – Requires Bucket Name, Access Key, and Secret Key

    • Enhanced CSRF Security (Optional)

      • Resolvable URL and Port for qTest Manager

      • Resolvable URL and Port for qTest Sessions

      • Resolvable URL/Domain for external defect tracker (e.g. – JIRA)

    • Secret key – You can generate the first key from the installation wizard. After you generate a secret key, make sure you save and use the same key for all of your qTest applications, on all instances.

  • Insights

    • Port to be used for communications (HTTP or HTTPS)

    • Directory for custom report and dashboard files - Location may be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation should also have read permission for this file and path recursively

    • Enhanced CSRF Security (Optional) –

      This may affect Insights performance and features such as (Embedded Reports/Dashboard, Shareable Dashboard, and Rapid Dashboard)

      • Resolvable URL and Port for qTest Manager

      • Resolvable URL and Port for qTest Sessions

  • Parameters

    • Port to be used for communications (HTTPS)

    • Secret key – You can generate the first key from the installation wizard. After you generate a secret key, make sure you save and use the same key for all of your qTest applications, on all instances.

  • Launch

    • Port to be used for communications (HTTPS)

    • Fully Qualified Domain Name, Hostname, or IP Address to construct the application URL – This must be resolvable outside of the server

    • Integration secret key – You can generate the first key from the installation wizard when you install qtestctl. After you generate a secret key, make sure you save this key in a safe place. You must use the same key for all nodes that run Manager or Launch during installation and upgrades.

  • Pulse

    • Port to be used for communications (HTTP or HTTPS)

    • Fully Qualified Domain Name, Hostname, or IP Address to construct the application URL – This must be resolvable outside of the server

    • Directory to logging storage - Location should not be inside the directory tree of the qTest application (i.e. /qtestctl). The user executing the qtestctl installation should also have read permission for this file and path recursively

    • Resolvable URL and Port for qTest Manager

    • Choose which version of the Pulse Executor to install

  • Scenario

    • Port to be used for communications (HTTP or HTTPS)

    • Fully Qualified Domain Name, Hostname, or IP Address to construct the application URL – This must be resolvable outside of the server

    • Secret key – You can generate the first key from the installation wizard. After you generate a secret key, make sure you save and use the same key for all of your qTest applications, on all instances.

Download and Start the Installation Package

  1. Request the installation files through the OnPremises New Install Form.

    Complete the OnPremises Technical Services Request form (opens in new tab) to request assistance or obtain self-installation links, whether you're upgrading or performing a fresh install.

  2. Once the OnPremises New Install Form is completed and submitted, the download link will be emailed to you from our Implementation Team.

  3. Download and extract the zip file to a folder on the disc.

  4. Navigate to the extracted folder at \path\to\qtestctl\

  5. Run the following command to start the installation:

    path\to\qtestctl>qtestctl.bat
The installation package may take a few minutes to unzip.

Choose the Applications to Install

A default value is provided for each prompt in the square brackets. You can press Enter to use our default values, or input your own values and then press Enter.

Provide a Yes (y) or No (n) response to the following question. Your response provided here will determine which components are installed on this Linux machine.

  • qTest Manager: [Y] or [N]

  • qTest Sessions: [Y] or [N]

  • qTest Parameters: [Y] or [N]

  • qTest Insights: [Y] or [N]

  • qTest Launch: [Y] or [N]

  • qTest Pulse: [Y] or [N]

  • qTest PulseOld: [Y] or [N]

  • qTest Scenario: [Y] or [N] 

Not sure if you should choose Pulse or PulseOld for your installation? Take a look at which version of the Pulse Executor to install.

Configure Prerequisite Applications

Configure PostgreSQL Database

You will enter the PostgreSQL Database information you gathered above. You will only need to configure PostgreSQL if you have selected at least one of the following applications:

  • Manager

  • Sessions

  • Parameters

  • Insights

  • Launch

  • Pulse

  • PulseOld

  • Scenario

Configure Postgressearch

 

Configure TLS

To deploy the web apps with TLS, type "y" for Enable secured connection (Y/N) [N]. Then, input the path to the cert and key files :

  • cipher suite: This is the list of cipher suites the program uses in the ssl_ciphers.config file. You don't have to take any action here, but you can edit the configuration file to provide your own. The configuration file contains cipher format examples and details on how to provide your own ciphers.

  • certificate file: Absolute path to the certificate file on this server. Please use / in the path.

  • private key: Absolute path to the private key file on this server. Please use / in the path.

  • passphrase: Input if your private key has a passphrase

If you do not want to deploy the web apps with TLS, type "n" for Enable secured connection (Y/N) [N]: and move to configuring the qTest applications.

Configure qTest Applications

The following applications will be configured using the information you gathered above. The prompt will ask you for configuration details based on the applications you chose to install in Step 1. 

If you only chose one application in Step 1, then that one application will ask for configurations during the install process. 

qTest Manager

After configuring the basic ports and the URL address for qTest Manager, you can enable enhanced security features. To do so, select Y and whitelist your domains as required.

Example:

If you choose to use Amazon S3 as qTest Sessions storage by selecting amazon_s3 for storage type. Refer to Create an AWS S3 Bucket for qTest Attachment Storage to learn how to set up an Amazon S3 bucket as well to manage access permission.

qTest Sessions

If you want to store resource files on a local disk, enter "1" or "disk_storage" and input the storage location. The location should be an absolute path to the folder. Please use\ or / in the path. Recommend copying the path from the system file browser.

Example:

If you want to store resource files on Amazon s3 enter "2" or "amazon_s3" and input s3 access key, s3 secret key and bucket name.

Example:

 

Enable Sessions Enhanced Security Option

If you want to enable these security features for Sessions, select Y, and whitelist your domains in the form of regular expression.

qTest Insights

qTest Insights configuration options

When you're configuring qTest Insights, you'll have the following options:

  • Choose the http and https ports you want to use. Leave these commands empty to use the default ports.

  • Specify the directory you want to store saved reports and dashboards in. Leave this command empty to use the default storage option, /opt/insights.

  • Choose whether or not to enable the Insights advanced security option. This is disabled by default.

  • Pre-calculation of the new Insights beta reports is enabled by default.

    Please note that pre-calculation may take some time, depending on the amount of data and computing power you have. We highly suggest monitoring your database load and temporarily adding resources as needed during pre-calculation. We also recommend performing this deployment on Friday after working hours to ensure iETL has enough time to complete the initial computing.

    We don't recommend disabling pre-calculation, as the beta reports will still be visible without any data. However, disabling pre-calculation can be helpful if you're close to hitting the limits of your PostgreSQL database. Disabling beta report pre-calculation won't affect your existing reports.

     

Enable Insights Enhanced Security Option

If you would like to enable these security features for Insights, select Y and use a regular expression to whitelist your domains.

An example of whitelisted domains during Insights configuration

qTest Parameters

Example:

qTest Launch

Example:

qTest Pulse

When running the script (qtestctl) in any environment, if the user changes the default location of the Pulse log, they will get an error message (>>> Installer doesn't have necessary permission on \qtest-data\logs\pulse\pulse.log). To get past this error, the user needs to create a text file in the directory and then provide the full path & file name.

Example:

qTest Scenario

Example:

Review the Configuration

After all of the configurations are entered, they are stored in qTest.config file. You can open the file to review the configuration details.

  • If you need to modify a value, you can re-run the wizard (recommended) or modify the qTest.config file.

  • To restore the default configurations, delete qTest.config and re-run the wizard.

    Example:

Start the Deployment

  1. To start the deployment, execute this command:

    path\to\qtestctl>qtestctl.bat start

  2. The command will take control of the Command Prompt. Keep it running.

Note that the user who runs the command to start deployment must be the same user who ran the configuration wizard.

Build Successful

You will receive a Build Successful message once the installation is complete. 

Configure qTest Manager to Connect to qTest Applications

Follow the Configure qTest Applications guide to connect qTest Manager with the other qTest applications you installed. You should also verify that the applications can be accessed and working properly before performing the next and final step.

Stop the Running Process

Navigate back to the Command Prompt and stop the running process (Ctrl + C).

Switch to PostgreSQL search

Optionally, you can switch from Elasticsearch to PostgreSQL search after you install or upgrade OnPremises. PostgreSQL search is more stable and secure, but there are still a few known issues that we're currently working on.

To switch to PostgreSQL search, you'll need to update some variables in your qtestctl folder. During this transition, you'll need to turn off Elasticsearch indexing, turn on PostgreSQL indexing, and switch the user interface to the PostgreSQL index.

Note that, if you update all of these environment variables at once without giving your instance time to index, your search function won't return results until PostgreSQL is done indexing. However you decide to perform these configuration tasks, be sure to restart qtestctl for each configuration change.

Turn on PostgreSQL indexing

Initial indexing can take anywhere from a few minutes to a few days, depending on the size of your data and your processing power. While qTest does send a notification when indexing is done, if you miss this notification, you can check your main.log file to find out if your instance is done with initial indexing. Just go to opt/qtestctl/manager/build/logs and locate the main.log file. When indexing is finished, this log will display the following message: "Sending indexing completion notification to users".

After initial indexing, if you're ready to start using PostgreSQL, follow these steps:

  1. Stop the qTest Manager instance with the following command:

    systemctl stop qtest

  2. Find your qtestctl folder. By default, this is located in C:\qtestctl for Windows.

  3. Open the following file: qtestctl/manager/build.gradle.

  4. This file contains the instructions to initialize qTest Manager. Locate the DB_PASS list, which should look like this:

    Copy
      DB_PASS: "${Crypto.decryptString(config['manager.postgres.auth.pass'])}",
              'manager.test.configuration': configEnabled,
              S3_SECRET_KEY : Crypto.decryptString(config['manager.storage.s3.secretkey']),
              SSL_PASS: sslPass,
              SECRET_KEY: "${Crypto.decryptString(config['common.data.secretkey'])}",
              AES_SECRET_KEYS: "${Crypto.decryptString(config['common.data.passwordsecretkeys'])}"
      ])

  5. Add the following variables to the DB_PASS list:

    Copy
              DB_PASS: "${Crypto.decryptString(config['manager.postgres.auth.pass'])}",
              'manager.test.configuration': configEnabled,
          'qtest.elastic.search.replacement' : true,
              'qtest.index.elastic.search' : false,
              'qtest.index.Postgres' : true,
              S3_SECRET_KEY : Crypto.decryptString(config['manager.storage.s3.secretkey']),
              SSL_PASS: sslPass,
              SECRET_KEY: "${Crypto.decryptString(config['common.data.secretkey'])}",
              AES_SECRET_KEYS: "${Crypto.decryptString(config['common.data.passwordsecretkeys'])}"
      ]) 

  6. Save your changes to the file to apply them.

  7. Start your qTest Manager instance with the following command:

    systemctl start qtest

Note that, if you update all of these environment variables at once, your search function won't return results until PostgreSQL is done indexing. To avoid this, you can turn on PostgreSQL indexing with the 'qtest.index.Postgres' : true variable. When PostgreSQL is done indexing, you can then switch the user interface to this index with the 'qtest.elastic.search.replacement' : true variable. However you decide to perform these configuration tasks, be sure to restart qtestctl for each configuration change.

Verify PostgreSQL is active

After you've updated the qtestctl file, you can verify that PostgreSQL is functioning properly by reviewing the feature flags in Chrome.

Follow these steps to verify PostgreSQL:

  1. Open your Manager instance in Chrome, then navigate to the developer console. You can find this by right-clicking anywhere on the website and selecting Inspect from the dropdown.

  2. Navigate to the Console tab and enter the following command to view an expandable map of all the qTest feature flags:

    qtest.featureFlags

  3. Locate the following feature flags and verify that they match these listed states:

    • qtest-elastic-search-replacement: { boolVariation: True }: If this is set to true, the search results in the user interface are from the PostgreSQL index. If it is false, the results in the user interface are from the ElasticSearch index.

    • qtest-index-elastic-search: { boolVariation: False }: If this is set to false, Elasticsearch is not performing the indexing.

    • qtest-index-Postgres: { boolVariation: True }: If this is set to true, PostgreSQL is indexing.

    If everything matches, you've successfully switched the backend of your search functions to PostgreSQL.

Install qTest Applications as a Windows Service

We highly recommend you enable qTest applications to start automatically when Windows starts.

  1. Open a Command Prompt and navigate to path\to\qTestctl folder.

  2. Execute the following command to install qTest applications as a Windows service.

path\to\qTestctl>install.bat