Zephyr On-Premise Upgrade Instructions

Owned by Kevin Pham (Deactivated)
Last updated: Mar 13, 2024 by Christiane Gangloff
9 min read

Download Zephyr

Download Zephyr on the following page: Zephyr Download.

As you transition to Zephyr Enterprise v7.19.0, please be aware that the upgrade process may take more time, especially with substantial data. Prepare for possible downtime.
If you encounter any upgrade issues, like the "lock table size" error, review and adjust the MySQL settings.
If you require further assistance or encounter additional issues, we encourage you to contact our support team for resolution.

Pre-upgrade steps

Step 1 Zephyr Enterprise supports MySQLv8.0.x effective from Zephyr Enterprise v7.17. Therefore, if you use MySQL you need to upgrade your MySQL DB to v8.0.x before upgrading your Zephyr Enterprise to v7.17 and above.

The current Elasticsearch settings by default allow automatic index creation if a document is pushed into a non-existent index. With this feature and a loophole in Zephyr's indexing process, users can create new indexes without intending to. This causes an indexing issue, as the indexing percentage will drop to ~1%, and the index-relate functionality is affected.

To stop this, configure Elasticsearch to disallow any index for Zephyr. As a result, any index which begins with the name "Zephyr" will not be allowed for automatic creation.

Step 2: Follow this step if you want to use ES 8.6.2

To use ES 8.6.2, uninstall the previous Elasticsearch version before installing ES 8.6.2. Please see the Windows and Linux instructions below:

Uninstall the previous Elasticsearch version:

  1. If you installed it as a service, go to Control Panel > Uninstall a program and uninstall Elasticsearch.
    If you just unpacked the ZIP file, stop Elasticsearch and delete the elasticsearch-<version> folder from the computer:

  2. Download and configure Elasticsearch 8.6.2 as described in Steps to Install Elasticsearch.

  3. Start Elasticsearch by double-clicking the elasticsearch.bat file:

  4. To verify the version of ES in the browser, type the host name with port 9200.
    In the response - it should be 8.6.2

     

 

  1. Open the file {directory}/elasticsearch-<version>/config/elasticsearch.yml and save somewhere the http.port and transport.tcp.port values. You will need to specify these exact values later when installing Elasticsearch 8.6.2.

  2. Uninstall the previous Elasticsearch version:
    If you installed it using the ZIP file:
    Stop Elasticsearch. Stop the process and delete the folder.
    If you installed it using the RPM file:

    • Stop Elasticsearch by using the command below:
      /etc/init.d/elasticsearch stop

    • Uninstall Elasticsearch using the following command:
      yum remove elasticsearch

    • Delete the elasticsearch folder from the locations below by using the command rm -rf foldername:

      • /etc/elasticsearch

      • /var/lib/elasticsearch

      • /var/log/elasticsearch

  3. Download and configure Elasticsearch 8.6.2 as described in Steps to Install Elasticsearch.

  4. Start Elasticsearch:
    service elasticsearch start

  5. To verify the version of ES in the browser, type the host name with port 9200.
    In the response - it should be 8.6.2

     

Step 3: Take a backup of the entire database: Steps to take database backup.

Step 4: Take a backup of the attachments, which are located in the file system (separate from the database).

We suggest you take a backup of the entire folder which can be found in Windows under the Zephyr Directory (ZephyrDir) or in Linux within /zephyrdata.

Step 5: Check the Server.xml file for the AJP connector.

  1. Stop the Zephyr Server.

  2. Open the file zephyr/tomcat/conf/server.xml and comment out the line below:

    <!-- <Connector port="8009" protocol="AJP/1.3" redirectPort="8443" /> -->

  3. Save the file, exit, and then you can start the upgrade process.

If SSL is previously setup in Zephyr, take a copy of your Java keystore file which is present under the Zephyr/tomcat/conf path file. For special SSL consideration, we recommend viewing the following page: Special SSL Consideration.

Refer to the steps below to replace the recommended connector jar file for MySQL or MSSQL. The instructions are provided separately for each connector:

  1. Stop the Zephyr Server Service.

  2. Take a backup of the jdbc.properties file from location <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\classes

  3. Go to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder and take a backup of the old jar file i.e., mysql-connector-java-5.1.49-bin.jar from the lib folder.

  4. Remove the existing jar file (mysql-connector-java-5.1.49-bin.jar) from <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder.

  5. Download the recommended jar file. MySQL: mysql-connector-j-8.0.32.jar

  6. Copy the downloaded jar and paste it to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder.

  7. Go to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\classes folder. Open the jdbc.properties file and change the value in “jarFileName =” parameter to the used jar file name.
    For example, jarFileName = mysql-connector-j-8.0.32.jar

  8. Upgrade to 7.17

  9. During extracting files, we get a popup. Clicking Yes/No or Yes to All/ No to All does not affect upgrade process and the process completes.

  1. Stop Zephyr Server Service.

  2. Take a backup of the jdbc.properties file from location <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\classes

  3. Go to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder and take a backup of the old jar file i.e., sqljdbc42.jar from the lib folder.

  4. Remove the existing jar file (sqljdbc42.jar) from <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder.

  5. Download the recommended jar file. MSSQL: mssql-jdbc-11.2.3.jre8.jar
    The file will be downloaded as a zip with the name sqljdbc_11.2.3.0_enu.zip. Please extract this zip file.
    After downloading extract, the sqljdbc_11.2.3.0_enu.zip ->then go to \sqljdbc_11.2.3.0_enu\sqljdbc_11.2\enu folder -> and pick only "mssql-jdbc-11.2.3.jre8.jar

  6. Copy mssql-jdbc-11.2.3.jre8.jar and paste it to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\lib folder.

  7. Go to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\classes folder. Open the jdbc.properties file and append the parameters in the DB URL for ITCC and Dversion.
    Example as below:

    db.url = jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true;databaseName=itcc db.dversion.url = jdbc:sqlserver://localhost:1433;encrypt=true;trustServerCertificate=true;databaseName=dversion

  8. Go to <Zephyr installation directory>\tomcat\webapps\flex\WEB-INF\classes folder. Open the jdbc.properties file and change the value in “jarFileName =” parameter to the used jar file name.
    For example, jarFileName = mssql-jdbc-11.2.3.jre8.jar

  9. Now upgrade to 7.17

Step 7: Take a backup of the nodedata, which are located in the file system.

We suggest you take a backup of the entire folder which can be found in Windows under the Zephyr Directory (ZephyrDir) or in Linux within /nodedata.

Upgrade on Linux from Root to Root user

Step 1: Stop the Zephyr Service.

sh /opt/zephyr/tomcat/bin/shutdown.sh

Step 2: Run the installation file of Zephyr Enterprise:

Step 3: Select the Upgrade option:

Step 4: Select the Zephyr installation folder where Zephyr was installed:

Step 5: Specify the Elasticsearch IP address and port:

Step 6: The upgrade has completed successfully:

Step 7 (Optional): If needed, enable authentication in Elasticsearch. See detailed instructions.

Step 8: Once Zephyr is installed successfully, launch the application and wait until reindexing is completed.

Please refer to the Post-Upgrade Process section below.

 

Upgrade on Linux from Root to Non-root user

Step 1: Stop the Zephyr Service.

Step 2: Run the installation file of Zephyr Enterprise:

Step 3: Select the Upgrade option:

Step 4: Select the Zephyr installation folder where Zephyr was installed:
a. If you select the option 2- No, Manually, then you will have to change the ownership of the files manually. Click here for more steps.

b. If you select the option 1- Yes, automatically, then the installer changes the ownership of the files automatically. Depending on the number of files, this operation may take time.

Step 5: Specify the Elasticsearch IP address and port:

Step 6: The upgrade has completed successfully:

Step 7 (Optional): If needed, enable authentication in Elasticsearch. See detailed instructions.

Step 8: Once the upgrade is complete, navigate to {ZephyrDir}/tomcat/conf/server.xml
You need to change port to 1024 and above.

Step 9: Once Zephyr is installed successfully, launch the application and wait until reindexing is completed.

Please refer to the Post-Upgrade Process section below.

Post-upgrade steps

Post-upgrade recommendations

Step 1: After upgrading, we recommend users clear their browser cache when accessing their Zephyr application if you are experiencing issues regarding cached pages.

Step 2: After upgrading, we strongly recommend users to perform a re-index of your Zephyr instance to ensure the integrity of your data and information within the Zephyr instance. For more details on reindexing refer Full Reindex.

Step 3: After upgrading, your users must update their OAuth keys from within Zephyr again on the Defect Tracking page in the administration section.

  • With the updated authentication for Jira, Zephyr saves the entries in the database and requires a manual update for the OAuth keys. The user needs to manually reset the consumer key name and the consumer private key.

Step 4: Update the Tomcat configuration.

  1. Stop the Zephyr application server.

  2. Locate the server.xml file under the Zephyr installation directory. (Zephyr Directory}\tomcat\conf)

  3. Open the server.xml file and locate the <Host> tag.

  4. Add the following value below the <Host> tag:

  5. Save the server.xml file.

  6. Start the Zephyr application server.

Step 5: If Zephyr application does not start

  1. Verify the connector files in {Zephyr Directory}\tomcat\webapps\flex\WEB-INF\lib folder after upgrade.

  2. Remove one file (older file) if there are 2 connector files and start Zephyr application.

Post-upgrade recommendations for special considerations and scenarios

These scenarios are based on whether or not users may have certain features enabled (SSO/etc.) These are not applicable to all customers.

Step 1: If SSL is setup in the previous version of Zephyr, then follow the instructions in Special SSL Consideration.

Step 2: Create and Validate Webhooks (May apply to users upgrading from either Zephyr Enterprise 6.2 or an earlier release).

Re-create the Webhook

1. The user must map a Zephyr project to their Jira instance/project. When users map a single project to their Jira, all other projects will be mapped creating the webhook. Users can choose to select any project to map as it does not matter which project is selected. Once the user finishes mapping the project to their Jira, the webhook will be created successfully in Zephyr.

Validate the Webhook

2. For users, you may want to double check that the webhook is created by navigating to the Jira webhook page and validating that all of the Jira projects are included in the webhook JQL.

Step 3: Update ZBot. You can download the ZBot installation file either from Zephyr by clicking the username in the top-right corner and selecting Download ZBot from the dropdown, or by going directly to http://<your_zephyr_server>/zephyr/zbot .

Step 4: Users must disable binary logging in the MySQL 8.0.x. By default, the binary logging is enabled in MySQL 8.0.

SSO Consideration: If you have SSO set up, your users may run into the following scenario.

The Zephyr login page will now auto-redirect to the SSO page if zephyr is integrated with SSO. 

For the Internal-login page, there will be no redirection. On that page, the login will contain the same behavior in the scenario that the admin wants to change the integration.

https://<Zephyr domain>/flex/html5/internal-login

When a user logs out of the system, they will be able to view the 2 following options:

A normal login (Internal login for users)

A Single Sign-On login (SSO)

The advantage of this is that if an SSO user is logged into their SSO already and that user hits the Zephyr URL, the user does not need to type their username and password. When navigating to the Zephyr URL, the SSO user will automatically be logged into Zephyr. 

Rollback process

Rollback may be required in the following cases:

  • When the Zephyr server is not stopped prior to the user starting the upgrade process.

  • When Zephyr is configured with Tomcat VisualVM memory configuration and then the Zephyr server stopped and user performs an upgrade process.

If a rollback is required, follow the instructions in Zephyr On-Premise Rollback Process.