/
Zephyr On-Premise Upgrade Instructions

Zephyr On-Premise Upgrade Instructions

Owned by Kevin Pham (Deactivated)
Last updated: Dec 02, 2024 by Dominik Trygar
12 min read

Starting October 11, 2024 (Zephyr Enterprise 8.2), the Zephyr Enterprise documentation moved from its current location on Atlassian to a dedicated, standalone Zephyr Enterprise documentation page. Please see: https://support.smartbear.com/zephyr-enterprise/docs/en/zephyr-enterprise/zephyr-installation-and-upgrade-guides/upgrade-zephyr-enterprise/zephyr-on-premise-upgrade-instructions.html

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.

  • Remember to take a full database backup before upgrading.

  • You need to restart the MySQL database before upgrading Zephyr Enterprise, as MySQL 8.0.30 and later versions have an issue.

Pre-upgrade steps

Step 1: Zephyr Enterprise supports MySQL v8.0.35, which is effective from Zephyr Enterprise v7.17. Therefore, if you use MySQL, upgrade your MySQL DB to v8.0.35 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 those 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 that 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

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: Restart MySQL DB before doing the upgrade.

Step 5: Back up the attachments located in the file system (separate from the database).

We suggest you back up the entire folder, which can be found in Windows under the Zephyr Directory (ZephyrDir) or in Linux within /zephyrdata.

Step 6: 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.

Step 7: Replace the recommended connector jar file.

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 the “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 the 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 the “jarFileName =” parameter to the used jar file name.
    For example, jarFileName = mssql-jdbc-11.2.3.jre8.jar

  9. Now upgrade to 8.x.

Step 8: Take a backup of the node data 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 /node data.

Step 9: Install RabbitMQ 3.12.10 (Optional):

RabbitMQ 3.12.10 is a robust messaging and streaming broker that's easily deployable across cloud environments and on-premises setups. Currently, installing RabbitMQ 3.12.10 is optional for the users. You can download RabbitMQ 3.12.10 - here.

Step 10: Install ZE-Services (Optional):

  • ZE-Webhook Service is the component responsible for accepting the incoming events from Jira and enqueues them to the message broker for further processing. You can download ZE-Webhook Service - here and find the installation instructions - here.

  • ZE-Consumer Service is the component that picks the enqueued events from the message broker and updates ZE with the incoming data. You can download ZE-Consumer Service - here and find the installation instructions - here.

  • ZE-AuditService is the component that acts as the incoming endpoint for the Audit Logs generated during the incoming webhook event processing and enqueues them to the message broker. You can download ZE-AuditService - here and find the installation instructions - here.

  • ZE-AuditProcessor is the component responsible for reading the enqueued audit logs from the message broker and inserting them into ZE. You can download ZE-AuditProcessor - here and find the installation instructions - here.

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: