Zephyr Production Installation for Linux

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

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/zephyr-on-premise-production-installation/zephyr-production-installation-for-linux.html

Prerequisites

  • Ensure your deployment can meet the system requirements for Zephyr.
  • Ensure you have your Zephyr license and any plugin license files that were provided. 

  • Download and install or upgrade the required software dependencies: 
    • Java JDK - one of the following:
      • OpenJDK 17.0.10 (recommended): Installation instructions - here
      • Oracle Version 17.0.10: Download - here / Installation instructions - here
    • MySQL: 8.0.35  Download - here / Upgrade / Installation instructions - here 
    • MySQL Connector: Download - here
    • Elasticsearch: v. 8.6.2: Download - here / Installation instructions - here
    • Zephyr Linux Installer: Download - here
    • RabbitMQ 3.12.10 (Optional - Java 17 required): Download - here
    • ZE-Services (Optional - Java 17.0.10 required):
      • ZE-Webhook: Download - here / Installation instructions - here
      • ZE-Consumer Deployment: Download - here / Installation instructions - here
      • ZE-AuditService Deployment: Download - here / Installation instructions - here
      • ZE-AuditProcessor Deployment: Download - here / Installation instructions - here


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

In a nutshell

The procedure to install Zephyr Server on Linux includes the following steps:

  1. Install Java:
  2. Install MySQL 8.0.35:  A database server is required to use Zephyr, and MySQL is the default for single server installations. If you plan to use MS SQL or Oracle, please review our Zephyr Data Center installation instructions.
  3. Configure MySQL:  See the recommended database settings below.
  4. Install Elasticsearch: Zephyr supports Elasticsearch 8.6.2. Elasticsearch must be installed as a separate process. Zephyr Server installations allow you to install this on the same VM as the Zephyr Server application.
  5. Upload Zephyr License: The Zephyr installer requires access to the license file provided. It will need to be first uploaded to the file system of the server.
  6. Upload the MySQL Connector: The Zephyr installer requires access to the MySQL connector jar file downloaded. It will need to be first uploaded to the file system of the server.
  7. Install / Configure Zephyr server: The installer will guide you through the application configuration options necessary for a new installation.
  8. Set ulimit in Linux: Increase ulimit on the server to 65535.
  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. Java 17 is required for using RabbitMQ.
  10. Install ZE-Services (Optional): Java 17 is mandatory for using ZE-Services:
    • ZE-Webhook Service is the component responsible for accepting the incoming events from Jira and enqueues them to the message broker for further processing.
    • ZE-Consumer Service is the component that picks the enqueued events from the message broker and updates ZE with the incoming data.
    • 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.
    • ZE-AuditProcessor is the component responsible for reading the enqueued audit logs from the message broker and inserting them into ZE.
    • ZE-Serviced Docker contains the docker images of all these services. This provides flexibility to the users to host and run these services as individual containers.

  1. The rest of this guide explains these steps in more detail.

Install & configure MySQL

  1. Install MySQL Server according to the instructions for your Linux distribution:
    For MySQL 8.0.35 - https://dev.mysql.com/downloads/mysql/8.0.html

  2. Configure MySQL with the following settings below and after configuration, restart the MySQL service. You will need to edit the my.cnf file and add the following configuration settings.  Depending on your Linux distribution, this may be in the /etc folder. 

[mysqld]
user=mysql
max_allowed_packet = 150M
max_connections = 600
default-storage-engine=INNODB
character-set-server=utf8
collation-server=utf8_unicode_ci
sql_mode=NO_ENGINE_SUBSTITUTION,STRICT_TRANS_TABLES

[mysqld_safe]
default-storage-engine=INNODB
character-set-server=utf8
collation-server=utf8_unicode_ci

[mysql]
max_allowed_packet = 150M

[mysqldump]
quick
max_allowed_packet = 150M


NOTE: You may run into an issue where the "max_connections" setting does not actually reflect in MySQL. This could be due to a file open limit built into the Linux operating system. Refer to these instructions for how to setup MySQL and Systems to adjust for the "LimitNOFILE" setting.


For MySQL 8.0 - https://dev.mysql.com/doc/refman/8.0/en/using-systemd.html

Install & configure Elasticsearch

Elasticsearch is required to be installed as a separate system service. For information on how to install it, see Steps to Install Elasticsearch.

After you install Elasticsearch, start the service and make sure it is running.

Install Zephyr

Make sure you have installed Elasticsearch prior to installing Zephyr.

  1. Ensure the installer file has the proper permissions to be executed:

    chmod +x zephyr_(Build Number)_linux_setup.sh

  2. Launch the setup file with the -c command line option as shown below, and ensure you launch it as sudo or root: 

     ./zephyr_(Build Number)_linux_setup.sh

  3. You will be prompted to continue with the installer.

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

  4. You may be prompted to choose between a new install or an upgrade.

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

  5. You will be prompted to confirm your system meets the Zephyr Server Requirements. Please review that your system meets the requirements before proceeding.

    Requirements
Server
OS:               RedHat Enterprise
                     CentOS
                     Ubuntu/Debian
                     SUSE/openSUSE
CPU:            Quad-core CPU Intel Pentium or AMD Opteron (2Ghz or higher)
RAM:            Minimum 16GB; Preferred 16GB
Disk Space:   At least 5GB Free
Networking:   Wired Ethernet
                     Static IP address
                     If Firewall exists, please allow ports
                     80, 443, 1024, 8443, 8005, 8009, 3306
Account:      Installer and services will be installed as the current user

  6. You will be prompted to agree to the Zephyr EULA.

    License Agreement
D Software End User License Agreement
IMPORTANT - PLEASE READ CAREFULLY:

This End User License Agreement ("Agreement") constitutes a valid and
binding agreement between D Software, INC. (”d software,” ”WE” or ”US”) and
you, as either an individual or a single business entity ("you," "your" or
"user") for the use of the Zephyr x.x software, ANY files that are delivered
to you by d software to modify the Zephyr x.x software product, any online
or enclosed documentation, and any updates, fixes and upgrades provided to
you (collectively, the ”Software”). You must FIRST READ AND ACCEPT THE TERMS
OF THIS LICENSE AGREEMENT by clicking on the ”i agree” checkbox below in
order to install and use the Software.

  7. Use the enter key until you see the following then enter 1 to agree to the terms.

    I accept the terms of this license agreement [1], I do not accept the terms of this license agreement [2, Enter]

  8. You will then be prompted to enter the path to place the Zephyr home directory.  

    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
[/usr/local/zephyr]

  9. You will then be prompted to choose an installation type. For information on how to deploy Data Center, see Set Up Zephyr Data Center.

    Choose deployment type:
Server deployment [1, Enter], Data Center deployment [2]

  10. You will then be prompted to locate your license file.

    License File
License Key File:
[/home/zephyr/license.lic]

  11. You will then be prompted to choose a port to run Zephyr on. By default, Zephyr runs on port 80 (for root user) and port 1024(for non-root user)

    .

    Customization
Server Port :
[80]

  12. You will then be prompted to choose a Tomcat Server Shutdown Port.  We recommend you leave it to the default port.

    Tomcat Server Shutdown Port:
[8005]

  13. You will then be prompted to choose a database system. Use the default MySQL.

    Note: If you had just uninstalled. Please wait few minutes for the port to get free and try again.
Configure Database
Database Type:        
MySQL [1, Enter]

  14. You will then be prompted to provide a database username. Note: The database user must be able to create, update, and alter permissions in the database.

    Database Character Set:  utf8
Username:
[]

  15. You will then be prompted to provide a database password. 

    Password:                 
[]
root

  16. You will then be prompted to provide a database connection string. If you installed MySQL on the same server as Zephyr, you can use jdbc:mysql://localhost:3306/

    Database URL Configuration:
Sample URL:               jdbc:mysql://localhost:3306/
Database URL:
[]

  17. You will then be prompted to provide a connection string for Elasticsearch.  By default, Elasticsearch will bind to the IP configured in the elasticsearch.yml file edited earlier in the installation instructions. For example: http://192.168.56.101:9200

    Configure Elasticsearch
Enter the hostname or IP address and 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
[]

  18. Zephyr will now install the required files and setup the MySQL database.

    Extracting files ..
# ************************************************************

  19. Zephyr installation is now complete and the service should have started. You can choose 'N' when prompted to Launch Zephyr Desktop and connect to Zephyr from your desktop machine.

    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]

To start Zephyr:

cd /usr/local/zephyr/tomcat/bin

./startup.sh

To stop Zephyr:

cd /usr/local/zephyr/tomcat/bin

./shutdown.sh

Set ulimit in Linux

Increase ulimit on the server to 65535:

  1. Stop the Zephyr Service.

  2. As the root user, open the file /etc/security/limits.conf for editing and add these lines at the end:

    <zephyr_user> soft nofile 65535
<zephyr_user> hard nofile 65535

    replacing <zephyr_user> with the user used to install Zephyr.

3. Start a new session and then start the Zephyr service.