Upgrade Steps for Linux from Root to Non-root User

Steps to perform before the upgrade

Caution

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

  • Zephyr Enterprise Release 8.1 and later supports the latest Java 17 or OpenJDK 17.0.10 versions. You can download Java 17 and OpenJDK 17.0.10  from the respective download page.

  1. Back up your Zephyr data, node data, and the database.

  2. Restart MySQL DB before doing the upgrade.

  3. Save all the contents of the following pages (license details, the start and end dates, indexing statistics, the current JVM size, and so on). You will need them for post-upgrade verification:

    • https://<your instance>.yourzephyr.com/flex/assets/html/version.html

    • https://<your instance>.yourzephyr.com/flex/version

    A screen appears providing detailed information on the Zephyr Application version, server configurations details such as the license details and server information.

  4. Copy somewhere the following files:

    • {Zephyr directory}\zephyr\tomcat\conf\server.xml

    • {Zephyr directory}\zephyr\tomcat\conf\web.xml

    • {Zephyr directory}\zephyr\tomcat\webapps\flex\WEB-INF\classes\jdbc.properties

    • {Zephyr directory}\zephyr\tomcat\conf\<SSL certificate>

  5. Back up the Zephyr data folder located in the common shared storage. If it is not there, back up the {Zephyr directory}\zephyrdata folder on each Zephyr node.

  6. Back up the node data folder located in the common shared storage. If not, back up each Zephyr node's {Zephyr directory}\nodedata folder.

  7. If you are not using the latest supported version of Elasticsearch 8.6.2, install it.

  8. Do the echo of the $ZEPHYR_HOME environment variable. If nothing is returned, set the ZEPHYR_HOME environment variable:

    export ZEPHYR_HOME='Path of the Zephyr Dir'

Important

Please take care of it if you have two or more nodes while upgrading the cluster environment:

The process of installing, updating, and executing the node occurs in a single step, starting from copying the update files.

Do not run the Upgrader simultaneously on all nodes, as it may lead to issues with database consistency.

First, execute the Upgrader on a single node until it is complete, then upgrade the rest of the nodes.

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. Installing Java 17 is required for using RabbitMQ. You can download RabbitMQ 3.12.10 - here.

10. Install ZE-Services (Optional): Upgrading to Java 17 is mandatory for using ZE-Services:

  • ZE-Webhook Service is the component responsible for accepting incoming events from Jira and enqueuing 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 queued 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 queues 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.

Tip

RabbitMQ and ZE Services should be installed in a separate server as we require Java 17.

The upgrade procedure

  1. Stop the Zephyr service on all Zephyr cluster nodes:

    cd <ZephyrDir>/tomcat/bin
sudo ./shutdown.sh

  2. Upgrade Zephyr on the first node using the installer:

    ./zephyr_(Build Number)_linux_setup.sh

Starting Installer ...
This will install Zephyr x.x on your computer.
OK [o, Enter], Cancel [c]

  3. When prompted to choose between a new installation and upgrading, choose Upgrade:

    1. update ownership of files to the current user manually:

      Choose type:
Install [1, Enter], Upgrade [2]
2

Ownership change
Some files in your Zephyr installation belong to a different user than the current user which is used for the upgrade.
Are you sure you want to update ownership of files to the current user automatically?
Yes, automatically [1, Enter], No, manually [2]
2


Since you have selected to change the Ownership of the file manually please follow this document https://zephyrdocs.atlassian.net/wiki/spaces/ZE/pages/3655106561/Change+Ownership+of+the+File+in+Linux
Rolling back changes ...

      Note

      As you selected to change the ownership manually, you must make the changes manually.

    2. update ownership of files to the current user automatically:

      Choose type:
Install [1, Enter], Upgrade [2]
2

Ownership change
Some files in your Zephyr installation belong to a different user than the current user which is used for the upgrade.
Are you sure you want to update ownership of files to the current user automatically?
Yes, automatically [1, Enter], No, manually [2]
1


Ownership of the file change is in progress. The time taken depends on the number of files and the size of your data. Please wait.
Note: If you are running the upgrader in the command prompt/Linux shell, please don't enter or press any key until the next message appears, otherwise upgrade may fail.
Ownership change of files is completed.

Upgrade is in progress. Time taken to upgrade depends on the size of your data. Please wait.
Note: If you are running the upgrader in command prompt/linux shell, please don't enter or press any key until next message appears, otherwise upgrade may fail

      Important

      Wait until you get the next prompt.

      Select Destination Location
Setup will install Zephyr into the following folder.
To continue click Next. If you would like to select a different folder, click Browse
<location of zephyr>

At least  5120 MB of free disk space  is required.
Available disk space:  256042 MB
Configure Elasticsearch
Enter the hostname or IP address and HTTP port used by Elasticsearch. For example: http://localhost:9200.
Multiple Elasticsearch nodes should be separated by comma. For example: http://localhost:9200,http://localhost:9201
ES Host URL
[http://localhost:9200]
Extracting files ...

After the installation is complete, you will see the following:
ZephyrService.sh may or may not start automatically. Please check and start manually if not started.
Done! 
Zephyr x.x has now been installed on your computer. 
Zephyr Desktop will now be launched automatically.
You can access additional help from the Zephyr installation.
Click Finish to exit setup.
Launch Zephyr Desktop?
Yes [y, Enter], No [n]

  4. Choose No for now.

  5. After you install Zephyr, make sure it is up and running. When Zephyr starts, you will see the following line in the zephyrlocation/tomcat/logs/thedinc.log log file:

    *****************
Zephyr Started
****************

  6. Stop the Zephyr service:

    cd <ZephyrDir>/tomcat/bin
./shutdown.sh

  7. Copy the SSL certificate files with those you saved at step 3 to the following folder if Zephyr is configured to use SSL:

    {Zephyr directory}\zephyr\tomcat\conf\<SSL certificate>

    Important

    Now go to another Zephyr cluster node and repeat all the upgrade steps described above.

  8. After you upgrade Zephyr Enterprise on all the nodes, you need to modify the following file on each node:

    <Zephyr Directory>/tomcat/webapps/flex/WEB-INF/classes/hazelcast.properties

    In this file, find the following lines and change the values as shown below:

    • zephyr.hz.cluster.enabled=false - set it to true.

    • zephyr.hz.cluster.name=zephyr-hazelcast-cluster - specify a unique name for each cluster, for example,

      zephyr-hazelcast-cluster_smartbear.

    • zephyr.hz.interfaces.enabled=false - set to true.

    • zephyr.hz.interface=127.0.0.1 - This is the IP of the IP interface. Replace it with an IP address that has asterisks instead of the last two components. For example:

      zephyr.hz.interface= 192.168.*.*

    • zephyr.hz.tcp-ip.enabled=false - set it to true.

    • zephyr.hz.members=127.0.0.1 - specify each node's IP addresses and port number separated by a comma. For example:

      zephyr.hz.members=192.168.0.1:5701,192.168.0.2:5701

  9. Update the SSL port to 1024 and above in the server.xml file.

  10. After modifying the hazelcast.properties file, start Zephyr on all the nodes by using the following commands:

    cd <zephyrDir>/tomcat/bin
./startup.sh

    When Zephyr starts, you will see the following line in the zephyrlocation/tomcat/logs/thedinc.log log file:

    *****************
Zephyr Started
****************

Steps to perform after the upgrade

  • Check whether Zephyr and Elasticsearch are up and running.

  • Check the logs for any errors and make sure that all the patches have been applied successfully.

  • Log in as an Administrator and trigger the Full Reindexing manually.

  • Check the re-indexing status:

    https://<your instance>.yourzephyr.com/flex/assets/html/version.html

  • This Step is only applicable if the ZE-Service is enabled - update the Jira Configuration for the new ZE-Services:

    1. Once the upgrade is successful, on login into Zephyr, the user will get the below popup. (If Jira is integrated before the upgrade)

      ZE_service_01.png

    2. Once the user navigates to the Jira Integration page → the Jira connections will be highlighted in RED as shown in the screenshot below:

      ZE_service_02.png

    3. Once all services are up and running → For Automatic webhook management → click on the Update Webhook button from the Jira Integration page.

      ZE_service_03.png

    4. In Jira, the webhook URL will be updated as per the new webhook URL:

    The new webhook URL would be something like: https://webhook.yourzephyr.com/v1/jira/webhooks/callback

  • This Step is only applicable if the ZE-Service is enabled. For Manual webhook management, copy the URL from the popup as shown in the below screenshot and go to Jira, to create a webhook with the new URL. The below popup will appear when integrating a Zephyr project with a Jira project or In Jira Integration → click on the Edit icon under the Action column and save the Jira Integration again.

    ZE_service_04.png

See Also

Set Up Zephyr Data Center Cluster

In this section:
© 2024
Publication date: