2025.8 OnPremises Single Server 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 single RHEL/Ubuntu machine. Please read the instructions thoroughly before starting your upgrade.

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:

• Get started with qTest 2025.8 OnPremises

• 2025.8 OnPremises Prerequisite Software for Linux and Kubernetes

• Server Sizing Guide

• Back up your qTest data before you upgrade.

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.

If you need to change your previous configurations, review the application checklist provided in 2025.8 OnPremises Single Server 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.

Stop qTest Applications

1. Access your qTest Manager server.

2. Log in as root user on your command shell.

3. Access the existing qTest installation directory.

   Example: /usr/local/qTestmanager93/qTestctl

4. Execute the command below to stop qTest applications.

   # systemctl stop qTest

5. Remove the qTest service.

   # ./uninstall

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. Access the qTest server.

4. Log in as a root user on your command shell.

5. Download qTest installer and move to desired installation path.

                       # wget <DOWNLOAD_URL>
   # mv <qtest_package_name>.tgz /path/to/install/location

6. Extract the qTest installer in the installation path and navigate into the new path. 

   # tar -zxvf <qtest_package_name>.tgz -C /path/to/install/location && cd /path/to/install/location

7. Execute the qTest installation script.

   # ./qtestctl

   or

   # bash qtestctl

8. 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 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 Scenario: [Y] or [N]

• qTest PulseOld: [Y] or [N]

• qTest Scenario: [Y] or [N] 

Configure Prerequisite Applications

Configure PostgreSQL Database

Review the 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.

• Hostname/IP

• Port

• Database Superuser - You can use the standard PostgreSQL user. If you require a separate user, it must have equivalent superuser permission. Your PostgreSQL setup must have superuser access, so you can't use managed PostgreSQL services that don't grant native superuser access. Learn more about the limitations of managed cloud PostgreSQL services in our Knowledge Base (opens in a new tab).

• Database Superuser Password

• TLS Certificate - The location of the TLS root certificate is required for installation. Make sure that the permissions and ownership allow the user installing qTest to access the path and certificate files recursively. For more information on PostgreSQL TLS connections, refer to the official documentation found at https://www.postgresql.org/docs/current/ssl-tcp.html.

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

qTest Manager

Example:

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

Example:

Example:

Enable Sessions Enhanced Security Option

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

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.

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.

qTest Parameters

Example:

qTest Launch

Example:

qTest Pulse

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. Copy the license folder /.tc from the previous release.

   cp -r ../qtestctl-1030/manager/build/.tc manager/build
   

2. Execute this command, to start the deployment:

   # ./qTestctl start

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

Configure and Test Connectivity to qTest Applications

You will receive a Build Successful message once the installation is complete. Follow the Configure qTest Applications guide 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 next step.

Stop the Running Process

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

Install qTest Applications as a Service

We highly recommend you enable qTest applications to automatically start on system startup.

1. In the Command Prompt, press `Ctrl + C` if qTestctl is running.

2. Navigate to the folder /home/qTestctl

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

     /home/qTestctl=> ./install

4. You have now finished upgrading qTest applications.

5. Access to qTest Sessions and verify the new version.

Migrate Data from Insights 2025.2 to Insights 2025.8

1. Navigate to the Root folder of Insights 2025.2:

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

   • If using a directory that can be accessed from Insights 2025.2 and 2025.8 (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 2025.8 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.

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