2025.8 OnPremises Single Server Upgrade Guide for Windows

In this article, we provide step-by-step instructions to upgrade qTest components from 2025.2 to 2025.8 OnPremises on a single Windows machine. Please read the instructions thoroughly before starting your upgrade.

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.

If you are upgrading qTest, it is highly recommended that you clear your qTest browser cache after receiving qTest 2025.8.

  • Windows: Ctrl+F5

  • Mac/Apple: Apple+R or Command+R

  • Linux: F5

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. Retry starting the Command Line Wizard again.

Before You Begin

Read the following:

The Command Line Wizard will prompt you for each installation instruction. You need to perform action items and gather specific connection information before you begin the upgrade process.

Enter in the same configurations as in your 2025.2 qTest.config file within the Command Line Wizard unless there are configuration changes to account for.

It is not recommended to copy the previous configuration file.

If you need to change your previous configurations, review the application checklist provided in 2025.8 OnPremises Single Server Installation Guide for Windows so you can see what information you will need.

Ports

Make sure the appropriate Ports for the prerequisite applications and qTest applications are open prior to any self-assisted 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.

Stop qTest Applications

  1. Open the Command Prompt as an Administrator and navigate to C:\qTestctl folder

  2. Execute the command below to stop qTest applications.

    C:\qTestctl>net stop qTest

  3. Remove the qTest service. 

     C:\qTestctl>uninstall.bat

Backup qTest Manager Data

Follow the Back up and Restore qTest Data guide for instructions.

Download and Start the Installation Package

  1. Request the installation files through the OnPremises Upgrade 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 Upgrade 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 disc.

  4. Navigate to the extracted folder at 

      C:\path\to\qtestctl

  5. Run the following command in a terminal window to begin the installation

    path\to\qTestctl>qTestctl.bat.

  6. The Command Line Wizard will prompt you for each installation instruction. You may need to perform action items and gather specific connection information before you begin the installation process. Enter the same configuration items from the previous version qtest.config file unless there are changes to the previous configuration that requires new information.

    Do not copy the qtest.configuration or any other file from the previous installation.

Choose the Applications to Upgrade

Provide a Yes (y) or No (n) response to the following question. Your response provided here will determine which components are upgraded on this Windows 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

Review your PostgreSQL Database information you copied from your previous deployment. If you need to enter new values you may do so.

Example:

Configure Elasticsearch Database

PostgreSQL 13.x and Elasticsearch 7

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

Configure qTest Applications

The following applications will be configured using the information you copied from your previous deployment package. The prompt will ask for configuration details based on the applications you chose to upgrade in Step 1.

Example: If you chose to upgrade one application in Step 1, then you will only supply configurations to the Command Line Wizard for that one application on this machine.

qTest Manager

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 stores 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 / in the path.

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:

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.

Sessions Enhanced Security Option

During an attempted CSRF attack, user credentials may potentially be inherited and then used to maliciously perform undesirable actions, usually affecting a change of state of server. Please note that this does not result in any data theft. SSL must be enabled.

  • qTest Managers HTTP or HTTPS Port

  • URL to access qTest Manager outside of this machine

  • qTest Sessions HTTP or HTTPS Port

  • URL to access qTest Sessions outside of this machine

  • External Defect Tracker domain, such as Jira

qTest Insights

If you chose to specify a directory to store your saved reports and dashboards for 2025.2, and this directory can be accessed from Insights 2025.8, specify this directory path during your upgrade to Insights 2025.8. For example, if you choose D:/data/insdata, which is completely independent of Insights qtestctl 2025.2 and 2025.8, you would need to specify this path during your upgrade.

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.

qTest Insights configuration options

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:

  1. To start the deployment, execute this command:

    qTestctl.bat start

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

Build Successful 

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

Configure qTest Manager to Connect to qTest Applications

Refer to Configure qTest Applications to configure qTest Manager to connect with the other qTest applications you installed. You should also verify that the applications can be accessed and working properly before performing the final steps.

Stop the Running Process

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

Install qTest Applications as a Windows Service

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

  1. Navigate to the folder C:\qTestctl-6.20

  2. Execute the command below to install the new qTest service. 

                        C:\qTestctl-6.20>install.bat

  3. You have now finished upgrading qTest applications.

  4. Access qTest applications and verify the new versions.

Migrate Data from Insights

  1. Navigate to the Root folder of Insights:

    • If using the default directory (Function.AppPhysicalPath) to store saved reports and dashboards in Insights, then use this root folder: \qtestctl\insights\build\tomcat\webapps\ROOT\Function.AppPhysicalPath

    • If using a directory that can be accessed from Insights (ex: D:\data\insdata), then navigate to that root folder.

  2. Copy the following folders:

    • SavedBookmarks

    • SavedDashboards

    • Custom Reports

  3. Move the copied folders to a new location for Insights at:

    • If using the default directory (Function.AppPhysicalPath) to store saved reports and dashboards in the qTest Insights configuration above, then paste to \qtestctl\insights\build\tomcat\webapps\ROOT\Function.AppPhysicalPath

    • Otherwise, paste to the directory (ex: D:\data\insdata) you specified in the qTest Insights configuration above.

Import qTest License

After the upgrade, you will need to manually copy the qTest License file from Manager 2025.2 and then import it to 2025.8. (These instructions are also covered in the Configure Manager article linked above.)

  1. Access your qTest Manager instance via your browser using the URL as specified in the qTest.config file.

  2. You will be redirected to the Licenses - Users tab in the Site Administration panel.

  3. Select the Import License File button.

  4. Browse to your license file located under the installation directory for qTest Manager 2025.2:

    Example: <installation_dir>\manager\build\.tc\license.lic

  5. Your license file will import into qTest Manager 2025.8.

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.