Zephyr On-Premise Upgrade Instructions for Linux

Download Zephyr

Download Zephyr on the following page: Zephyr Download.

  • Zephyr Enterprise currently supports only upgrades to the supported versions. See Zephyr End-of-Life Policy.If you need to upgrade from an older version, contact support.

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

Important

As you transition to Zephyr Enterprise version 8.4.5, 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.

Caution

  • Run the following query to check for data corruption before upgrading your MySQL database to version 8.4.5 or later. See, Validating Data Corruption in MySQL Database for more information.

  • Remember to take a full database backup before upgrading.

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

Pre-upgrade steps

Step 1: Zephyr Enterprise supports MySQL v8.4.5, effective from v8.5. So, if you use MySQL, upgrade your MySQL DB to v8.4.5 before upgrading your Zephyr Enterprise to v8.5

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

Important

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

On Linux

  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. Refer to Elasticsearch Single Node - On Linux for installation and configuration details.

  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

    3652223022.png

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

Step 4: Back up the attachments 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 in /zephyrdata.

Step 5: Restart MySQL DB before doing the upgrade.

Step 6: Check the Server.xml file.

  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. The connector location will look like the following once the above lines are added and additional other highlighted changes are made:

    <Connector port="443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled=" true"
acceptCount="100"
maxThreads="150" scheme="https" secure="true"
clientAuth="false" sslEnabledProtocols="TLSv1.2" sslProtocol="TLS"
keystoreFile="C:/Program Files/Zephyr/tomcat/ssl/mysslkey.jks" keystorePass="changeit">
<!-- SSLHostConfig added to ensure proper initialization -->
<SSLHostConfig hostName="_default_">
<!-- Using JKS keystore directly, no need for separate certificate/key files if using JKS -->
<Certificate certificateKeystoreFile="C:/Program Files/Zephyr/tomcat/ssl/mysslkey.jks"
certificateKeystorePassword="changeit"
certificateKeystoreType="JKS"/>
</SSLHostConfig>
</Connector>

  4. Save the file, exit, and start the upgrade process.

    Important

    If SSL is previously set up in Zephyr, copy your Java keystore file, which is present under the Zephyr/tomcat/conf path file. For special SSL consideration, see here.

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:

Replace the Connector for MySQL

  1. Stop the Zephyr Server Service.

  2. Take a backup of the jdbc.properties file from the 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 for the following: mysql-connector-java-5.1.49-bin.jar, mysql-connector-j-8.0.32.jar from the folder.

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

  5. Download the recommended jar file.

    MySQL: mysql-connector-j-9.2.0.jar (Path: https://downloads.mysql.com/archives/get/p/3/file/mysql-connector-j-9.2.0.zip).

    For example, jarFileName = mysql-connector-j-9.2.0.jar

  6. Copy the downloaded jar and paste it into <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-9.2.0.jar

  8. Upgrade to 8.x.

  9. During file extraction, we get a pop-up. Clicking  Yes / No  or  Yes to All /  No to All  does not affect the upgrade process; it completes.

Note

If it is a cluster setup, you must perform the above steps on all nodes.

Replace the Connector for MSSQL

  1. Stop Zephyr Server Service.

  2. Take a backup of the jdbc.properties file from the 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

  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 (Path: https://go.microsoft.com/fwlink/?linkid=2221563)

    The file will be downloaded as a zip with the name sqljdbc_11.2.3.0_enu.zip. Please extract this zip file.

    MSSQL: mssql-jdbc-11.2.3.jre8.jar file can be found inside the downloaded zip path sqljdbc_11.2.3.0_enu\sqljdbc_11.2\enu folder.

  6. Copy mssql-jdbc-11.2.3.jre8.jar and paste it into <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

Note

You must perform the above steps on all nodes if it is a cluster setup.

Step 8: Take a backup of the node data in the file system.

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

Note

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

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 proceed with upgrading the rest of the nodes.

Step 9:Stop the Atemis Services if you are upgrading from 8.3 and later versions.

Step 10: Install RabbitMQ 4.1 (Optional).

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

Step 11: Install ZE-Services (Optional).

Note

  • This is optional for the current release.

  • Java 17 is required for the service.

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

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

  • 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 for the message broker. You can download ZE-AuditService here and find the installation instructions.

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

Tip

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

Upgrade on Linux from Root to a Root User

Step 1: Stop the Zephyr Service.

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

Step 2: Run the installation file of Zephyr Enterprise:

1558437071.png

Step 3: Select the Upgrade option:

1558437074.png

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

1558437077.png

Step 5: Specify the Elasticsearch IP address and port:

1558437080.png

Step 6: The upgrade has been completed successfully:

1558437083.png

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

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 a Non-Root User

Step 1: Stop the Zephyr Service.

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

Step 2: Run the installation file of Zephyr Enterprise:

01_Step2.PNG

Step 3: Select the Upgrade option:

02_Step3.png

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

  • If you select option 2, you will have to manually change the files' ownership. For more information, see the steps.

    03_Step4a.png

  • If you select option 1—Yes, automatically, the installer will change files. Depending on the number of files, this operation may take time.

    04_Step4b.PNG

Step 5: Specify the Elasticsearch IP address and port:

05_Step5.png

Step 6: The upgrade has completed successfully:

06_Step6.png

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

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

07_Step8.png

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

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

Step 2: After upgrading, if the Index is not 100, then it is recommended for users to perform a re-index of your Zephyr instance to ensure the integrity of your data and information in the Zephyr instance. For more details on reindexing, refer  to

Step 3: 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:

    <Valve className="org.apache.catalina.valves.ErrorReportValve" showReport="false" showServerInfo="false" />

  5. Save the server.xml file.

  6. Start the Zephyr application server.

Step 4: 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 5: Update Artemis (If upgrading from Zephyr 8.3 and above)

After taking a data backup, you can update the Artemis Service. Refer to Upgrading Zephyr Version from 8.3 or later with Artemis Service for more information on updating Artemis Service for Windows and Linux.

Step 6: Right after the installation or upgrade of Zephyr Enterprise.

Step 7: After the installation or upgrade of Zephyr Enterprise, Zephyr will start, If Artemis does not start up initially. To start Artemis follow these steps:

  1. Move to the ZEPHYR_HOME/artemis folder atthe Zephyr installation location.

  2. To start Artemis explicitly, run using sh artemisStartup.sh.

  3. To stop Artemis explicitly, run using sh artemisShutdown.sh.

To start and stop Artemis along Zephyr

Perform the following steps:

  1. To start Artemis along with Zephyr, run the Zephyr startup command.

  2. To start Zephyr without Artemis, run the startup—sh -artemis=false.

  3. To stop, run the Zephyr shutdown command. This also stops Artemis if it is running.

Step 7 (optional): This Step only applies if ZE-Service is enabled. Once the upgrade is successful:

  1. On logging into Zephyr, the user will get the following 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 below screenshot:

    ZE_service_02.png

  3. Once all services are up and running, → For Automatic webhook management → click 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.

Step 8(optional): This Step only applies if 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

Post-upgrade steps

Post-upgrade recommendations for special considerations and scenarios

These scenarios are based on whether users may have certain features enabled (SSO/and so on). These do not apply to all customers.

Note

Users must disable binary logging in MySQL 8.4.5. By default, the binary logging is enabled in MySQL 8.4.5. For more information, see Step 5: Install Zephyr and Connect to the Database.

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.

There will be no redirection to the internal login page. The login will behave the same way 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 following two options:

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

Important

Linked test case statuses in Jira

From Zephyr Enterprise 7.21 and later, we've removed the support of the remote link created in Jira. However, any old or existing links in Jira that have remote links pointing to test cases in Zephyr will still display in Jira.

This is because Zephyr cannot update/remove those existing remote links during the upgrade process.

However, we recommend using the ZE Plugin to view the traceability report in Jira Zephyr Enterprise Jira Plugin.

If the Zephyr application does not start

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

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

Rollback process

Rollback may be required in the following cases:

  • When the Zephyr server is not stopped, the user starts the upgrade process.

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

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

In this section:
© 2025
Publication date: