2025.8 OnPremises Load Balancing Upgrade Guide for Linux

In this article, we provide step-by-step instructions to upgrade qTest components from 2025.2 to 2025.8 OnPremises on a load balancing environment, where qTest components are running on their own RHEL/Ubuntu server. 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. Hint: In the event, you cannot start the Command Line Wizard again after terminating the configuration, backup then remove the qTest.config file. Retry to start 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, please review the application checklist provided in 2025.8 OnPremises Load Balance Installation Guide for Linux 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.

qTest Applications with a Load Balancing Model

Refer to the Select your OnPremises Systems and Deployment Model for Manager 2025.8 to view different deployment model samples.

The sample below uses five servers.

  • 1 load balancing servers

  • 3 application node servers

  • 1 database server 

  • Server 1: Manager Load Balancer is a server that acts as a load balancer for the two qTest Manager servers. We will install and use NGINX on this server for that purpose.

  • Server 2: 

    • qTest Manager application node which is an instance of qTest Manager deployed in a Linux server.

    • qTest Sessions application node which is an instance of qTest Sessions deployed in a Linux server.

    • NFS Client

  • Server 3:

    • qTest Manager application node which is an instance of qTest Manager deployed in a Linux server.

    • qTest Sessions application node which is an instance of qTestSessions deployed in a Linux server.

    • NFS Client

  • Server 4:

  • Server 5: Prerequisite applications, including Elasticsearch, PostgreSQL and the Shared Network Drive

    • PostgreSQL: a database engine used to manage qTest Manager, Sessions, Parameters, Insights, Launch, Pulse, and Scenario. All application nodes must use the same PostgreSQL database.

    • Elasticsearch: a database engine used for enhanced search capabilities

    • Shared Server: a server that hosts shared components that are required to run qTest Manager and Sessions. It should be accessible from all application nodes to store attachments and search index. 

      • NFS Server (Network File Systems): used to share directories and files with others over a network. We will use NFS to manage and share files created by qTest Manager and Sessions applications deployed on the two qTest Manager and qTest Sessions servers.

        • IPv4 Public IP: we will not use the public IP address since this server will not be exposed to the outside world

        • Private IP: 10.0.10.230

You will need to configure the Application nodes with your Load Balancer. You can use any load balancing tools or services which are being used in your organization. Our sample uses NGINX.
Your team members will access qTest Manager via the URL in the application nodes as configured in the Load Balancer.

Upgrade qTest Applications

In the Load Balancing model, there are multiple application nodes (qTest Manager and qTest Sessions on Server #2 and Server #3 in the above diagram). You will need to upgrade each server and take into consideration the applications installed on each server.

Upgrading an application node will follow the same set of instructions as upgrading qTest applications on a single server. Refer to 2025.8 OnPremises Single Server Upgrade Guide for Linux to upgrade qTest application nodes on a Linux server.

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 after you install or upgrade OnPremises and your program is finished with initial indexing. 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, you'll need to update some variables in your qtestctl folder. You'll need to turn off Elasticsearch indexing, turn on PostgreSQL search indexing, and switch the user interface to the PostgreSQL search index.

Note that you can choose to have Elasticsearch and PostgreSQL search perform indexing at the same time, but it will incur additional processing costs. We suggest that you choose one or the other, instead of running both.

Enable PostgreSQL search

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 directory. By default, this is located in cd /opt/qtestctl/.gradle/libs for Linux.

  3. Create a backup of the existing WAR file with the following command: cp qtest-2025.8.0.war qtest-2025.8.0.war.bkp.

  4. Move this backup into a new directory with the following commands:

    Copy 
    mkdir qtest123
    cd qtest123

    You'll want to keep this backup in case you want to revert to your original WAR file at any point.

  5. Extract the original WAR file with the following command:  jar -xvf ../qtest-2025.8.0.war

    If you can't use the jar command, first install Java with this command:

    Copy 
    sudo apt update
    sudo apt install openjdk-17-jdk

  6. Locate and open the LaunchDarkly configuration file from the unpacked WAR file: WEB-INF/classes/launchdarkly/launchdarkly.json

  7. In the LaunchDarkly configuration file, locate the "qtest-index-elastic-search", "qtest-elastic-search-replacement", and "qtest-index-postgres" feature flags and update them to match the following code snippet:

    Copy 
      "qtest-index-elastic-search": false,
      "qtest-elastic-search-replacement": true,
      "qtest-index-postgres": true

  8. Save your changes to the LaunchDarkly configuration file.

  9. Repack the WAR file with the following command: jar -cvf ../qtest-2025.8.0.war *

  10. Start your qTest Manager instance with the following command: systemctl restart 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.PostgreSQL' : 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 search is active

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

Follow these steps to verify PostgreSQL search:

  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-PostgreSQL: { boolVariation: True }: If this is set to true, PostgreSQL is indexing.

    If everything matches, you've successfully switched to PostgreSQL search.