Menu

9.8.3 OnPremise Single Server Upgrade Guide for Windows

Overview

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

To request assistance with upgrading or obtain the self-upgrade links, complete the Upgrade Request Form and reference the OnPremise Upgrades Guide.

Note: If you are performing a fresh install, use the OnPremise New Install Form and reference the OnPremise Install Guide.

New for This Release: Enhanced Security Enablement for Sessions and Insights

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. Additional details are provided below. 

About the Command Line Wizard

The qTest 9.8.3 Command Line Wizard is a command-line interface application that allows you to configure basic settings for qTest applications in your purchased 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.

Known Limitations

  • The Command Line Wizard and qtestctl do not support the character "$". Therefore, a password, username, or any other value that you would enter in a prompt should not contain "$." 
    • qtestctl does not support special characters "#or "?" in your PostgreSQL password
  • For Windows users, if you type "Ctrl-C" to terminate the wizard, there will be exceptions shown in the terminal before the wizard stops. You can ignore these exceptions. The configurations are still persisted successfully to the qtest.config file.

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 upgrade process.

It is highly recommended you use the same configurations as in your 9.7.1 qtest.config file and copy those to your new deployment package, so they will be your default values in the 9.8.3 Command Line Wizard.

If you need to change your previous configurations, please review the application checklist provided here 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
PostgreSQL 5432
ElasticSearch 9200
Network Drive 2049

 

LINUX NON-DOCKER AND WINDOWS

Product HTTP Port HTTPS Port
Manager 8080 8443 
Sessions 9080 9443
Scenario 6080 6443
Insights 10080 10443
Parameters 5080 5443
Pulse 4080 4443
Launch 3080 3443

IMPORTANT: 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, Sessions and Parameters

  1. Backup your databases following these instructions.

Download and Start the Installation Package

  1. Request the installation files through the OnPremise Upgrade Form which is also available at the top of this article.
  2. Once the OnPremise 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 \path\to\qtestctl\
  5. Access the qtestctl 6.4 deployment folder and copy the qtest.config file from your prior deployment to your new qtestctl 6.5 deployment package. This will copy your previous values and set them as the displayed default values in the Command Line Wizard.
  6. Run the following command to start the installation:
    path\to\qtestctl>qtestctl.bat --offline

Note: A default value is provided for each prompt in the square brackets. If you copied your qtest.config file from your previous deployment to your new deployment package, then your previous configurations will be the default values displayed. You can press Enter to use your default values, or input new values and then press Enter.

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

Configure Prerequisite Applications

Configure PostgreSQL Database 

Review your PostgreSQL Database information you copied from your previous deployment. If you need to enter new values you may do so. You will only need to configure PostgreSQL if you have selected at least one of the following applications:

  • Manager
  • Sessions
  • Parameters
  • Insights
  • Launch
  • Scenario
  • Pulse

Example:
configure_postgres_9.6.1_version.png

Configure ElasticSearch Database

Configure_ElasticSearch.png

 

Configure SSL

This must also be enabled if you are planning to use the Enhanced Security Options listed below. 

If you do not want to deploy with SSL, type "n" for Enable secured connection (Y/N) [N]: and move to configure the qTest applications.SSL_config_no.png

If you do want to deploy with SSL, type "y" for Enable secured connection (Y/N) [N]: and input the path to cert and key files :

  • cert: absolute path to the certificate file on this server. Please use \ or / in the path. Recommend copying the path from system file browser.
  • key: absolute path to the private key file on this server. Please use \ or / in the path. Recommend copying the path from system file browser.
  • passphrase: input passphrase if your key has passphrasewindows-config-ssl.png

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:
Manager_config.png

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 \ or / in the path. Recommend copying the path from system file browser.

Example:sessions_disk_storage_config.png

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:
sessions_amazon_config.png

Note: if you choose to use Amazon S3 as qTest Sessions storage by selecting amazon_s3 for storage type. Refer to this article to learn how to setup 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 i.e. JIRA

q4_19_installer_csrf_sessions_manager.png

qTest Insights

For Insights 1.21.9, if you chose to specify a directory to store your saved reports and dashboards and this directory can be accessed from Insights 1.21.9 and 1.21.12 (ex: D:\data\insdata, as this directory, is completely independent of the Insights qtestctl 1.21.9 and 1.21.12 directory.)

Then to upgrade Insights to 1.21.12, at the command "Specify the directory to store saved reports and dashboards [Function.AppPhysicalPath]" input the suitable path (ex: D:\data\insdata) of the directory used to store your Insights 1.21.9 data.

Example:
insights.png

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

3 Insights features are impacted by this new security configuration:

  • embed reports/dashboard
  • shareable URL dashboard
  • rapid dashboard 

Insights allow users to generate an HTML template and embed it into an external website ex: Confluence. Therefore, the domain of this website need to be included in the Whitelist domain. SSL must be enabled. 

  • qTest Managers HTTP or HTTPS Port
  • URL to access qTest Manager outside of this machine
  • qTest Insights HTTP or HTTPS Port
  • URL to access qTest Insights outside of this machine
  • External Reporting domain i.e. Confluence

q4_19_installer_csrf_insights.png

qTest Parameters

Example:

param_w.png

qTest Launch

Example:
Launch_w.png

qTest Pulse

Example:
configure_pulse_q4_19.PNG

qTest Scenario

Example:

configure_scenario_q4_19.PNG

Review the Configuration

After all 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:
setup_deployment_complete.png

Start the Deployment

To start the deployment, execute this command:

qtestctl.bat --offline start

The command will take control of the Command Prompt. 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

Follow this article 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 and final step.

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 automatically start when Windows starts, you need to install it as a Windows service. For more information on installing qTest service, read the qtestctl as a Service article.

  1. Navigate to the folder
    C:\qtestctl-6.5
  2. Execute the command below to install the new qTest service.
    C:\qtestctl-6.5>install.bat
  3. You have now finished upgrading qTest applications.
  4. Access qTest applications and verify the new versions.

Migrate Data from Insights 1.21.9.2 to Insights 1.21.12

Stop Insights 1.21.9.2 before performing data migration.
C:\[path_to_NEW_qtestctl]>net stop qtest

  1. Navigate to the Root folder of Insights 1.21.9.2:
    • If using the default directory (Function.AppPhysicalPath) to store saved reports and dashboards in Insights 1.21.9.2 then use this root folder: \qtestctl\insights\build\tomcat\webapps\ROOT
    • If using a directory that can be accessed from Insights 1.21.9.2 and 1.21.12 (ex: D:\data\insdata) then navigate to that root folder.
  2. Copy the following folders:
    • SavedBookmarks
    • SavedDashboards
  3. Move the copied folders to a new location for Insights 1.21.12 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
    • 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 9.7.1 and then import it to 9.8.3. (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 v9.7.1:
    Example: <installation_dir>\manager\build\.tc\license.lic
  5. Your license file will import into qTest Manager 9.8.3.
Powered by Zendesk