2.2.3 [Non-Docker Linux] Update qTest 5.x (or below) to qTest 7.2.3

Important_icon.pngImportant:

  • Please thoroughly review the instructions below to upgrade qTest to the latest version, before starting the upgrade process. We recommended to use copy & paste for the code scripts.
  • Prerequisite packages must be installed and running prior to upgrading qTest and Session Manager.
  • Make sure that you back up your data prior to the upgrade process. Please follow these instructions.

A. Hardware requirements for 100~300 users. For more than 300 users, please consider a cluster solution.

  1. For qTest:
    • CentOS 6.4 Final - 64 bit or Ubuntu 12.04 - 64 bit
    • RAM: 8GB AVAILABLE
    • Minimum HDD free space: 70 GB is for qTest and data storing (500 GB HDD or above is recommended for growing plan)
    • Processor: Quad core ~2.3Ghz or up
  2. For Session Manager:
    • CentOS 6.4 Final - 64 bit or Ubuntu 12.04 - 64 bit
    • RAM: 8GB AVAILABLE
    • HDD: 125 IOPS
    • CPU: quad core 2.0GHz
  3. For DBMS (if a separated DBMS is deployed):
    • RAM: 4GB AVAILABLE or more
    • HDD: 120 (10k rpm) or more
    • CPU: Quad core ~2.3Ghz or up

B. Software requirements

  1. For the Enterprise package, you will need to upgrade qTest AND qTest Sessions. If qTest Sessions is not yet installed, follow the directions to install prerequisite packages and qTest Sessions. Before the upgrade, please install prerequisite packages follow these instructions 
    • MySQL version 5.6 (qTest currently only works on version 5.6 and is not supported on version 5.7 or any future versions at this time.)
    • MySQL Connector version 5.1.34+
    • RabbitMQ (only if using a load balancer)
    • Redis version 2.8.19+
    • Elasticsearch version 1.7.3 (download link)
    • PostgreSQL version 9.3+
  2. For Pro or Pro + Explorer packages, you only need to upgrade qTest only, NOT Session Manager. Before the upgrade, please follow these instructions to install the followings:
    • MySQL version 5.6 (qTest currently only works on version 5.6 and is not supported on version 5.7 or any future versions at this time.)
    • MySQL Connector version 5.1.34+ 

»Upgrading qTest on Linux

»Upgrading qTest Sessions

»Installing qTest Sessions on Linux

Upgrading qTest on Linux

NOTE: The instructions below use the scenario of upgrading qTest from 5.0.11 to 7.2.3 and the base installation is directory /usr/local. As you copy & paste the scripts provided, please make sure to adjust the file names and directory according to your current qTest version and install directory.

A. Download qTest packages

1. Login as root on command shell of Linux server. Open the installation directory and download the qTest upgrade package. Then, extract the qTest upgrade file.

NOTE: These instructions provide scripts using the example where the base install directory is /usr/local and you are upgrading qTest 5.0.11 to 7.2.3.

$ sudo su
# cd /usr/local
# wget https://s3.amazonaws.com/qtest-storage/linux-package/7.2/qtest-linux-upgrade-7.2.3.tar.gz

 

B. Upgrade qTest

1. Access the installation directory of your current qTest. In this example, 

# cd /usr/local/qtest-linux-5.0.11

2. Copy qtest-linux-upgrade-6.2.4.tar.gz to the above directory.

# cp /usr/local/qtest-linux-upgrade-7.2.3.tar.gz .

3. Extract qtest-linux-upgrade-x.x.x.tar.gz

# tar -zxf qtest-linux-upgrade-7.2.3.tar.gz

4. Edit the file upgrade_qtest.sh.

# cd /usr/local/qtest-linux-5.0.11
# vim upgrade_qtest.sh

4.1 Fill in the corresponding properties:

  • Specify information to connect to your MySQL server; including its host, port, credentials to login and the path to MySQL Connector/J's jar file. If you are only upgrading qTest and do not want to change MySQL connection information, leave EX_MYSQL_PORT, EX_MYSQL_USER, EX_MYSQL_PASS and EX_MYSQL_HOSTNAME blank as below.
    # MySQL external configuration variables.
    EX_MYSQL_PORT="" //
    EX_MYSQL_USER="" //
    EX_MYSQL_PASS="" //
    EX_MYSQL_HOSTNAME="" //
    MYSQL_CONNECTOR_LIB_PATH="[Path_to_Connector_jar_File]" //eg: "/usr/local/mysql-connector-java-5.1.35/mysql-connector-java-5.1.35-bin.jar"
    

    button-round-warning-icon.pngNOTE: If you are upgrading from a version before qTest 5.0.x, you will need to add the last configuration for MySQL Connector

    MYSQL_CONNECTOR_LIB_PATH="[Path_to_Connector_jar_File]" //eg: "/usr/local/mysql-connector-java-5.1.35/mysql-connector-java-5.1.35-bin.jar"
  • If you are upgrading from qTest version 1.x, you will need to migrate your database.
    # Migrate embedded database to external database (only turn on (IS_MIGRATE_DB="Yes")  when upgrading from 1.x version to newer )
    IS_MIGRATE_DB="No"
    
  • If you want to change the configuration to enable SSL connection, then set SSL_REQUIRED="True" and specify the HTTPS port number.
    # Setting SSL mode, please prepare your certificate before turn on this mode.
    WEB_HTTPS_PORT=443
    SSL_REQUIRED="No"

4.2. If you want to deploy qTest with a load balancer, edit file upgrade_qtest.sh and specify the following configurations

  • There must be one Notification Server and you will need to install it first.
    NOTIFICATION_NODE="Yes"
    
  • After you have install Application Server, you can install multiple Application Servers.
    NOTIFICATION_NODE="No"
    
    If the Application Server is in different host with the Notification Server, specify the connection to the Notification Server. If not, skip this block:
    NOTIFICATION_EXTERNAL="Yes"
    NOTIFICATION_EXTERNAL_URL="[EXTERNAL_URL]" //full URL from the external network to the notification server, including TCP port
    NOTIFICATION_INTERNAL_URL="[INTERNAL_URL]" //full URL from the internal network to the notification server, including TCP port
    
  • It is required to specify the connection to your Redis server
    CACHE_EXTERNAL="Yes"
    CACHE_ENDPOINT="[Redis_Host]"
    CACHE_PORT=[Redis_Port]
    
  • It is required to specify the connection and the user's credentials to connect to your RabbitMQ server
    MQ_HOST="[RabbitMQ_Host]"
    MQ_PORT=[RabbitMQ_Port]
    MQ_STOMP_PORT=[RabbitMQ_Stomp_Port]
    MQ_VHOST="[RabbitMQ_Virtual_Host_Name]"
    MQ_USER="[RabbitMQ_User]" //specify a user who has been granted to the virtual host
    MQ_PASSWD="[Password_Of_The_Above_User]"
    

4.3. Make sure property POSEIDON_SETUP_MODE is install and specify MySQL's connection information to create Poseidon database.

POSEIDON_DB_PORT="[Mysql_port]"
POSEIDON_DB_HOST="[mysql_host]"
POSEIDON_DB_USER="[mysql_user]"
POSEIDON_DB_PASSWD="[mysql_password]"
POSEIDON_SETUP_MODE="install"

5. After you have done editing the file, save and close it.

6. Execute upgrade_qtest.sh. 

 # ./upgrade_qtest.sh

While the command is being executed, you need to fill in the following information as prompted if SSL is enabled.

      • Private key path
      • Private key password
      • Certificate path
      • Chain certificate path (optional)
 # ./upgrade_qtest.sh
 Shutdown qTest if any instance is running...
 qTest stopping...
 Instance is running as PID=31123, shutting down...
 Instance is running PID=31123, sleeping for up to 60 seconds waiting for shutdown
 Instance shutdown gracefully
 qTest stopped.
 Begin upgrading qtest...
 Starting the setup process...

 Private key path: //path to your certificate key file.(Eg: /usr/local/cert/server.key)
 Private key password: //input your password here
 Certificate path: //path to your certificate file (eg: /usr/local/cert/server.crt)
 Chain certificate path (optional): //path to your chain certificate file

 Generates SSL keystore successfully!
 …

7. When the upgrade process is complete, you can start qTest service

# ./qtest_start.sh

Upgrading qTest Sessions

Download Sessions' upgrade package here.

NOTE: These instructions provide scripts using the example where the base install directory is /usr/local and you are upgrading Sessions 1.2.0. to 2.2.2

1. Login as root on command shell of Linux Server

$ sudo su

2. If qTest Sessions is running, please stop the service before upgrading.

# service explorerd stop

 

3. Extract the bundle and change the directory to sessions-linux-2.2.2

# cd /usr/local
# tar -zxf sessions-linux-2.2.2.tar.gz
# cd sessions-linux-2.2.2

4. Run the following command, specify the directory in which the old version of qTest Sessions was installed. The current conf/configurer.properties file will be renamed to configurer.properties.old. A new conf/configurer.properties file will be copied to that directory.

# ./installer -t upgrade -d /usr/local/sessions-linux-1.2.0

5. Open file conf/configurer.properties

# cd /usr/local/sessions-linux-1.2.0 
# vim conf/configurer.properties

6. Review and edit the following information:

  • Specify information to connect to PostgreSQL server; including host, port number, credentials and the schema name. The database schema must be created in advance. Please set db.action=1.
    # database configuration
    db.host=[PostgreSQL_IP_Address] //eg: 192.168.74.77
    db.port=[PostgreSQL_Port] //it is 5432 by default
    db.user=[PostgreSQL_super_user]
    db.password=[PostgreSQL_super_user_password]
    db.schema=[database_schema] //make sure that the schema is created 
    //before the installation. Refer to the instructions for CentOS or Ubuntu.
    db.action=1 //Please set this property to 1
    
  • Important_icon.pngImportant:

    • To avoid losing your data, please make sure to set db.action=1 

 

  • Specify information to connect to Redis server; including host and port number.
    # redis configuration
    redis.host=[Redis_IP_Address] //eg: 192.168.55.63
    redis.port=[Redis_Port] //it is 6379 by default
    
  • Specify the URL and the token to connect to your qTest instance.

    button-round-warning-icon.pngNOTE: Access to Resources page in your qTest application to get the Master Token. Click here for instructions.

    # qtest configuration
    qtest.url=[qTest_URL]
    qtest.master_token=[token]
    
  • Specify the information of your Elasticsearch server. qTest support one cluster and multiple nodes.
    # elastic search configuration
    es.http.host=[ElasticSearch_IP_Address] //eg: 192.168.74.67
    es.http.port=[ElasticSearch_HTTP_Port] //it is 9200 by default
    es.cluster.name=[Cluster_Name] //refer to HINT for how to collect cluster name
    
    es.nodes=1
    es.tcp.1.host=[Node_IP_Address] //eg: 192.168.74.67
    es.tcp.1.port=[Node_Port] //it is 9300 by default
    
    			

    button-round-warning-icon.pngHINT:

    • Click here for instructions to get your ElasticSearch's cluster name.
    • If you have more than one nodes, assign an ordinal to each node using property es.nodes. For example:
      # elastic search configuration
      es.http.host=[ElasticSearch_IP_Address] //eg: 192.168.74.67
      es.http.port=[ElasticSearch_HTTP_Port] // it is 9200 by default
      es.cluster.name=[Cluster_Name]
      
      es.nodes=1
      es.tcp.1.host=[Node1_IP_Address] //eg: 192.168.74.67
      es.tcp.1.port=[Node1_Port] //it is 9300 by default
      
      es.nodes=2
      es.tcp.2.host=[Node2_IP_Address] //eg: 192.168.74.68
      es.tcp.2.port=[Node2_Port] //it is 9300 by default
      					
  • Specify which ports qTest Sessions will use. Set web.ssl.required=true if it will be using SSL connections (HTTPS).
    # application information.
    web.http.port=[HTTP_Port]
    web.https.port=[HTTPS_Port]
    web.shutdown.port=[Shutdown_Port]
    web.ajp.port=[AJP_Port]
    web.ssl.required=false //put "true" if you want to enable SSL connection
    

    Important_icon.pngImportant:

    • Please make sure the ports you've specified above are not blocked by your firewall.
    • When specifying the port numbers, make sure the selected ports are all available. Click here for instructions to check which ports are in use.
  • Declare qTest Sessions's URL.
    # declare eXplorer API url to use.
    web.url= //The protocol (HTTP or HTTPS) is required in the URL
    
    Eg:
    # declare eXplorer API url to use.
    web.url= http://sample.org:8080
    
    It will be filled in qTest's API URL. If it is left blank, the installer will use the default: http://[IP]:[port]/, in which IP is the host where qTest Sessions is installed, port is the HTTP port number.
  • Specify the storage configuration:
    • Specify where session data will be stored in:
      # storage configuration
      # storage.type suitable value (disk | s3 | riakcs)
      storage.type=disk
      						
    • If disk is chosen, specify the storage path:
      # disk storage configuration
      storage.rootPath=[Storage_Path_On_Local_Machine] //make sure that the directory is created before the installation
      

      button-round-warning-icon.pngHINT: You can use mkdir command to create a directory:

      # mkdir [Storage_Path_On_Local_Machine]
      
    • Otherwise, specify the following information:
      # s3 | riak storage configuration
      storage.url=
      storage.bucketName=
      storage.accessKey=
      storage.secretKey=
      storage.diable-dns-buckets=[true|false]
      						
  • Please do not modify the following section:
    # account configuration.
    account.username=admin
    account.password=51ca5dff068c393899233251450d95e2
    				

7. Save the above file after you have done modifying. 

8. Execute configurer.sh. The installation process starts. The progress is logged in explorer-installer-cli.log.

# ./configurer.sh
		

9. You will see the installation process on your console. If you enabled SSL connections (HTTPS) in the above step, you will be prompted to provide your certificates:

[ * ] Generate installation tasks.                      [ PASSED ]
Private key path: //path to your key file (eg: /usr/local/cert/server.key)
Private key password:
Certificate path: //path to your certificate file (eg: /usr/local/cert/server.crt)
Chain certificate path (optional):
Generates SSL keystore successfully!
    [ * ] Public session URL to qTest ...                   [ PASSED ]
/usr/local/build-release-15-1/sessions-linux-1.0.0/explorer-api/webapps/ROOT/WEB-INF/db /usr/local/build-release-15-1/sessions-linux-1.0.0
Unable to locate tools.jar. Expected to find it in /usr/local/build-release-15-1/sessions-linux-1.0.0/tools/java/lib/tools.jar
Buildfile: /usr/local/build-release-15-1/sessions-linux-1.0.0/explorer-api/webapps/ROOT/WEB-INF/db/liquibase.xml

dbPrepare:

dbInit:
[lb:updateDatabase] Starting Liquibase.
[lb:updateDatabase] Successfully acquired change log lock
[lb:updateDatabase] Dropping Database Objects in schema: explorer-api-67.public
[lb:updateDatabase] Creating database history table with name: public.databasechangelog
[lb:updateDatabase] Successfully released change log lock
[lb:updateDatabase] Successfully acquired change log lock
[lb:updateDatabase] Creating database history table with name: public.databasechangelog
[lb:updateDatabase] Reading from public.databasechangelog
[lb:updateDatabase] /usr/local/build-release-15-1/sessions-linux-1.0.0/explorer-api/webapps/ROOT/WEB-INF/db/changelog-master.xml: changelogs/changelog-init-db.xml::release-0.9.0::trongle: SQL in file sql/init-schemas.sql executed
[lb:updateDatabase] /usr/local/build-release-15-1/sessions-linux-1.0.0/explorer-api/webapps/ROOT/WEB-INF/db/changelog-master.xml: changelogs/changelog-init-db.xml::release-0.9.0::trongle: SQL in file sql/init-data.sql executed
[lb:updateDatabase] /usr/local/build-release-15-1/sessions-linux-1.0.0/explorer-api/webapps/ROOT/WEB-INF/db/changelog-master.xml: changelogs/changelog-init-db.xml::release-0.9.0::trongle: ChangeSet changelogs/changelog-init-db.xml::release-0.9.0::trongle ran successfully in 1005ms
[lb:updateDatabase] Successfully released change log lock

BUILD SUCCESSFUL
Total time: 6 seconds
/usr/local/build-release-15-1/sessions-linux-1.0.0
==========================================================================
   >>> BEGIN CHECKING REDIS SERVER.
==========================================================================
    [ * ] Server host: 192.168.74.67
    [ * ] Server port: 6379

    [ * ] Redis health check ...                            [ PASSED ]
    [ * ] Redis read-write check ...                        [ PASSED ]
    [ * ] Configure DB cluster ...                          [ PASSED ]
    [ * ] Configure ES cluster ...                          [ PASSED ]
    [ * ] Configure redis cluster ...                       [ PASSED ]
    [ * ] Configure file storage ...                        [ PASSED ]
    [ * ] Configure qTest account ...                       [ PASSED ]
    [ * ] Configure admin account ...                       [ PASSED ]
==========================================================================
   >>> END CHECKING REDIS SERVER.                           [ PASSED ]
==========================================================================
==========================================================================
   >>> BEGIN INITIATE ELASTICSEARCH SERVER.
==========================================================================
    [ * ] Server host: 192.168.74.67
    [ * ] Server port: 9200
    [ * ] Server protocol: HTTP

    [ * ] ElasticServer heath check ...                     [ PASSED ]
    [ * ] Create ElasticSearch Index ...                    [ PASSED ]
    [ * ] Create session mapping ...                        [ PASSED ]
    [ * ] Create application info mapping ...               [ PASSED ]
    [ * ] Create system info mapping ...                    [ PASSED ]
    [ * ] Create coverages mapping ...                      [ PASSED ]
    [ * ] Create time line mapping ...                      [ PASSED ]
    [ * ] Create screen mapping ...                         [ PASSED ]
    [ * ] Create note mapping ...                           [ PASSED ]
==========================================================================
   >>> END INITIATE ELASTICSEARCH SERVER.                   [ PASSED ]
==========================================================================
Configures eXplorer API successfully.
...

10. When the upgrade process is complete, you can start qTest Sessions service

# service explorerd start