Jira started as a popular tool used by software development teams to track and manage their projects. As the IT industry changed over the years, Jira has also grown to meet the demands and challenges faced by its users. Today, Jira has transformed from being a single application to a platform with many applications and solutions that can run on top of it, and it provides additional features and capabilities that go beyond issue tracking.

Atlassian, the company behind Jira, has several other products that make up the Jira family. These include the following:

• Jira Software: This is a product that focuses on software development. It allows project teams to run their software development projects using traditional waterfall and agile methodologies such as Scrum and Kanban.
• Jira Work Management: This is a product that is designed for non-software development teams, such as marketing, operations, and legal. It is perfect for general-purpose task management.
• Jira Service Management: This is a product for service desk teams. It is designed for running Jira as a support ticketing system, with a simplified user interface for the end users with a focus on customer satisfaction and Service-Level Agreement (SLA) goals.

At its core, the Jira platform provides many of its common functionalities for various products, such as user interface customization, workflows, and email notifications, while Jira Software and Jira Service Desk add specialized features on top of it.

Of course, being a platform means Jira also allows other third-party developers to develop solutions for it. Atlassian has a huge thriving ecosystem of products and solutions made by partners that add even more features to Jira. We will look at some of these solutions later in this book.

In this book, we will primarily focus on Jira Software, but we will also cover all the common features that are shared by all the applications, and how they can be used by them in their specific use cases. For this reason, the term Jira will be primarily used to refer to Jira Software, unless a specific distinction is needed.

Now that we have learned about the Jira platform and its various products, it is time to look at the newest member of the Jira family.

One of the biggest challenges users often face with Jira Server is scalability. When an organization’s Jira deployment grows to thousands of concurrent users and hundreds of thousands of issues, they will often start to experience performance issues, such as slower response times. While each new major release would include performance improvements, customers often had to archive and export old projects to another Jira instance or split up their one big instance into several smaller instances.

Some organizations can resolve this problem by migrating to the Jira Cloud offering. However, not everyone can move to the public cloud due to security, regulations, and other reasons, or they prefer to run Jira in their private cloud. This is where Jira Data Center comes in.

Jira Data Center is the new offering from Atlassian that replaces the old Jira Server and aims to address challenges that are often faced by organizations that need their Jira deployment to be performant, scalable, highly available, and secure.

With Jira Data Center, you can continue to host Jira yourself, with the aforementioned added benefits. Many additional features are added, such as support for Security Assertion Markup Language (SAML), Advanced Roadmaps for planning, and improved administrative functions.

Additional information

You can find a full list of differences between the old Jira Server and Jira Data Center at https://confluence.atlassian.com/enterprise/jira-server-and-data-center-feature-comparison-953651628.html.

So, how does Jira Data Center achieve all these benefits and improvements? Unlike Jira Server, where you have a single instance of Jira running, Jira Data Center allows you to run multiple Jira instances together as a single deployment, called a cluster. The following diagram illustrates a typical Jira Data Center deployment:

Figure 1.1 – Jira Data Center deployment

You will have one or more Jira instances, called nodes, running in a single cluster. All the Jira nodes will connect to the same database and file server, with a load balancer to distribute the traffic across all the nodes. This way, you have more computing power shared across the cluster, and you can add another node to the cluster at any time to add additional capacity.

Another good feature of Jira Data Center is that you do not need to run a cluster if you are not ready. You can run your deployment with a single node as a standalone, just as you would with the previous Jira Server. Then, when you need to, you can always convert your deployment into a cluster. Doing so gives you flexibility, as well as all the additional features that have been introduced in Jira Data Center. With a good understanding of Jira Data Center, let’s look at what we will need for deployment.

Before we can deploy Jira Data Center, we need to look at the hardware and software required for Jira, and how you want your deployment to be.

You can deploy Jira in two ways:

• Standalone: This is the same deployment as the classic Jira Server, where you have a single Jira instance serving your users. This is the easier option and does not require as many system resources. If you are just getting started, this is the option for you.
• Cluster: This is the deployment shown in Figure 1.1, where you can have multiple Jira instances (nodes) running in a cluster, and they all serve your users. If you need scalability, high availability, and other cluster-specific features, this is the option for you.

If you are unsure which option to start with, you can always start with the standalone option and switch to a cluster when you need all the features and benefits from a clustered deployment.

Now that we know what deployment options are available for Jira, let’s start looking at the hardware and software you will need.

Hardware requirements

For evaluation purposes, where there will only be a small number of users, Jira will run happily on any server that has a 1.5 GHz processor and 1 GB to 2 GB of RAM. As your Jira usage grows, a typical server will have a quad-core 2 GHz+ CPU and 4 GB of RAM dedicated to the Jira application, and at least 10 GB of hard disk space for your database.

For production deployment, as in most applications, it is recommended that you run Jira on its own dedicated server. There are many factors that you should consider when deciding the extent of the resources to allocate to Jira, especially in terms of how Jira will scale and grow in the future. When deciding on your hardware needs, you should consider the following:

• The number of active (concurrent) users in the system, especially during peak hours
• The number of projects, issues, and comments in the system
• The number of configuration items, such as custom fields and workflows

At times, it can be difficult to estimate these figures. As a reference, a server running with a 2.0 quad-core CPU and 4 GB of RAM will be sufficient for most instances with around 200 active users. If you start to get into thousands of active users, you will need to have at least 8 GB of RAM allocated to Jira (JVM). Once you have gone beyond a million issues and thousands of active users for a single Jira instance, simply adding raw system resources (vertical scaling) will start to yield diminishing returns. In such cases, it is often better to consider using the Data Center edition of Jira, which offers better scalability by allowing you to have multiple instances clustered together (horizontal scaling), with the added benefit of providing high availability.

Officially, Jira only supports x86 hardware and 64-bit derivatives of it. When running Jira on a 64-bit system, you will be able to allocate more than 4 GB of memory to Jira, which is the limit if you are using a 32-bit system. If you are planning to deploy a large instance, it is recommended that you use a 64-bit system.

Software requirements

Jira has three major requirements when it comes to software: it needs a supported operating system, a Java environment, and a database to store all of its data. In the following sections, we will discuss each of these requirements and the options that you have to install and run Jira.

Additional information

You can find the latest information on software requirements online at https://confluence.atlassian.com/adminjiraserver/supported-platforms-938846830.html.

Operating systems

Jira supports most of the major operating systems, so the choice of which operating system to run Jira on becomes a matter of expertise, comfort, and, in most cases, the existing organization’s infrastructure and requirements.

The operating systems supported by Atlassian are Windows and Linux. There is a Jira distribution for macOS, but this is mostly for evaluation purposes only. Amazon Web Services (AWS) and Microsoft Azure are also supported with quick-start templates.

With both Windows and Linux, Atlassian provides an executable installer wizard package that bundles all the necessary components to simplify the installation process. There are minimal differences when it comes to installing, configuring, and maintaining Jira on different operating systems. If you do not have any preferences and would like to keep initial costs down, CentOS Linux is a good choice.

Java platforms

Jira is a Java-based web application, so it needs to have a Java environment installed. This can be a Java Development Kit (JDK) or a Java Runtime Environment (JRE). The executable installer that comes with Windows or Linux includes a JRE. However, if you want to use archive distributions, you will need to make sure that you have the required Java environment installed and configured.

Jira requires a minimum version of Java 8. If you run Jira on an unsupported Java version or from an unsupported vendor, you may run into unexpected errors. The following table shows the supported Java versions for Jira:

Table 1.1 – Java platforms

You should also keep your Java versions up to date by running the latest patched version of either Java 8 or 11. This will ensure you have the latest bug and security patches to keep your environment secure.

Databases

Jira stores all its data in a relational database. While you can run Jira with H2 Database, the in-memory database that comes bundled with Jira, it is prone to data corruption. You should only use this to set up a new instance quickly for evaluation purposes, where no important data will be stored. For this reason, you must use an enterprise-level database such as MySQL for production systems.

Most relational databases available on the market today are supported by Jira, and there are no differences when you install and configure Jira. Just like operating systems, your choice of database will come down to your organization’s infrastructure/DevOps team’s expertise, experience, and established corporate IT standards. If you run Windows as your operating system, then you probably want to go with Microsoft SQL Server. On the other hand, if you run Linux, then you may want to go with PostgreSQL and MySQL.

The following table summarizes the databases that are supported by Jira at the time of writing. It is worth mentioning that both MySQL and PostgreSQL are open source products, so they are excellent options if you are looking to minimize your initial cost:

Table 1.2 – Databases

Take special note of the driver requirement for each database. Jira comes bundled with drivers for several of the databases, but some, such as Oracle, will require you to get the driver separately. You need to make sure you get the correct version of the driver to avoid any unexpected errors.

With the system and database requirements covered, it is time to move on to Jira itself.

Jira Data Center comes with several deployment options. The first choice you need to make is where you would like to deploy Jira. If you want to deploy Jira to AWS or Azure, Atlassian provides quick-start templates so that you can get up and running quickly.

If you want to deploy Jira to your hardware or other cloud vendors, or simply want to manage how you want the deployment to be, you can use the installation packages available. Jira installation packages come in two flavors:

• Executable installer: The executable installer provides a wizard-driven interface that will walk you through the entire installation process. It even comes with a Java installer to save you some time.
• TAR.GZ or ZIP archive: The archive package is similar to the executable installer, except it does not have an installation wizard, does not bundle Java, and will not configure Jira to run as a service.

You will also need to perform some post-installation steps manually, such as configuring Jira as a service. However, you do get the advantage of learning what goes on under the hood.

In our exercise, we will be using the installer package, but we will also cover the post-installation steps so that you have a good understanding of the various configuration options available. We will start by installing Java.

Installing Java

Since we will be using the installer package that’s bundled with Java, you can skip this section. However, if you are using the archive option, you need to make sure that you have Java installed on your system.

Jira 8 requires JRE version 8 as a minimum to run. You can verify the version of Java you have by running the following command in Command Prompt:

    java -version

The preceding command tells you which version of Java is running on your system, as shown in the following screenshot:

Figure 1.2 – Java version

If you do not see a similar output, then chances are you do not have Java installed. You will need to perform the following steps to set up your Java environment. Start by installing Java on your system:

1. Download the latest Java 8 or 11 from https://www.java.com/en/download/manual.jsp.

Note

At the time of writing, the latest version of Java 8 is JDK 8 Update 321.

2. Double-click on the downloaded installation file to start the installation wizard.
3. Select where you would like to install Java. Alternatively, you can simply accept the default values. The location where you install JDK will be referred to as JAVA_HOME for the remainder of this book.
4. Create a new environment variable named JAVA_HOME with the value set to the full path of the location where you installed Java. You can do this as follows:
   1. Open the System Properties window by going to About your PC from the Windows Start menu.
   2. Select the Advanced system settings option.
   3. Click on the Environment Variable button from the new popup:

Figure 1.3 – The JAVA_HOME environment variable

4. Add a new variable (either User or System) called JAVA_HOME and set its value to where you installed Java.

Now that you have a good understanding of Jira Data Center, the basic system requirements, and the various installation options, we are ready to deploy our own Jira instances.

We will start by installing Jira as a standalone deployment. We will perform our installation on a Windows platform and use PostgreSQL for the database. If you are planning on using a different platform or database, refer to the vendor documentation on installing the required software for your platform.

In this section, you will do the following:

• Install a fresh instance of Jira Software
• Connect Jira to a PostgreSQL database
• Configure the Jira instance to work in a cluster environment

We will continue to use this Jira deployment in subsequent chapters and exercises as we build our help desk implementation.

For our deployment, we will use the following:

• Jira Software 8.21.0
• PostgreSQL 12.9
• Apache web server
• Microsoft Windows

Let’s begin by installing Jira!

Installing Jira

Before we install Jira, here are two important directories we need to mention:

• JIRA_INSTALL: This is the directory where the Jira application will be installed
• JIRA_HOME: This is the directory that Jira will use to store some of its important configuration and data files

We will be referring to those two directories throughout this book. Now, on to the installation. There are generally two steps involved:

• Downloading and installing the Jira application
• Running through the Jira setup wizard

Let’s get started.

Obtaining and installing Jira

The first step is to download the latest stable release of Jira. You can download Atlassian Jira from https://www.atlassian.com/software/jira/update.

The Atlassian website will detect the operating system you are using and automatically suggest an installation package for you to download. If you intend to install Jira on a different operating system from the one you are currently on, make sure that you select the correct operating system package.

As we mentioned earlier, with Windows, there is a Windows installer package and a self-extracting archive package. For this exercise, we will use the installer package (Windows 64-bit Installer):

1. Double-click on the downloaded installation file to start the installation wizard and click on the Next button to continue:

Figure 1.4 – Jira installation step 1

2. Select the Custom Install (recommended for advanced users) option and click on the Next button to continue. Using the custom installation will let us decide where to install Jira and will also provide numerous configuration options, as shown in the following screenshot:

Figure 1.5 – Jira installation step 2

3. Select the directory where Jira will be installed. This will become the JIRA_INSTALL directory. Click on the Next button to continue:

Figure 1.6 – Jira installation step 3

4. Select where Jira will store its data files, such as attachments and log files. This will become the JIRA_HOME directory. Click on the Next button to continue:

Figure 1.7 – Jira installation step 4

5. Select where you would like to create shortcuts to the Start menu and click on the Next button to continue.
6. In the Configure TCP Ports step, we need to select the port that Jira will be listening on for incoming connections. By default, Jira will run on port 8080. If 8080 has already been taken by another application, or if you want Jira to run on a different port such as port 80, select the Set custom value for HTTP and Control ports option and specify the port numbers you want to use. Click on the Next button to continue:

Figure 1.8 – Jira installation step 6

7. Select whether you would like Jira to run as a service. If you enable this option, Jira will be installed as a system service and can be configured to start automatically with the server; refer to the Starting and stopping Jira section for more details:

Figure 1.9 – Jira installation step 7

8. For the final step, review all the installation options and click on the Install button to start the installation:

Figure 1.10 – Jira installation step 8

9. Once the installation is complete, check the Launch Jira Software in browser option and click on Finish. This will close the installation wizard and open your web browser so that you can access Jira. This may take a few minutes to load as Jira starts up for the first time:

Figure 1.11 – Jira installation step 9

That’s it! Congratulations, your Jira is installed and running. Now, let’s learn how to configure it.

The Jira setup wizard

If you chose the Launch Jira Software in browser option in the last step of the installation wizard, you should see the Jira setup wizard in your browser window. If not, you can browse to http://localhost:<port number> in your browser, where <port number> is the number you assigned to Jira in Step 6 of the installation process.

The easy-to-use setup wizard that comes with Jira will walk you through the process of completing your Jira setup. Here, you will be able to configure the database connections, default language, and much more.

The steps for this are as follows:

1. In the first step of the wizard, we need to select how we want Jira to be set up. Since we are installing Jira for production use, we will select the I’ll set it up myself option, as shown in the following screenshot:

Figure 1.12 – Jira configuration step 1

2. For the second step, we will need to select the database we want to use. This is where we configure Jira to use PostgreSQL as its database. If you select the Built In option, Jira will use its bundled in-memory H2 database, which is good for evaluation purposes. If you want to use a proper database, such as in our case, you should select the My Own Database option:

Figure 1.13 – Jira configuration step 2

Note

The Built In option is great for getting Jira up and running quickly for evaluation purposes.

After you have selected the My Own Database option, the wizard will expand for you to provide the database connection details. If you do not have the necessary database driver installed, Jira will prompt you for it.

Once you have filled in the details for your database, it’s a good idea to click on the Test Connection button to verify that Jira can connect to the database. If everything has been set up correctly, Jira will report a success message. You should be able to move on to the next step by clicking on the Next button. This may take a few minutes as Jira will now create all the necessary database objects. Once this is done, you will be taken to the next step of the wizard.

3. In the third step, you will need to provide some basic details about this Jira instance. Once you have filled in the requisite fields, click on Next to move on to the next step of the wizard:

Figure 1.14 – Jira configuration step 3

4. In this step, we need to provide a license key for Jira. If you have already obtained a license from Atlassian, you can paste it into the Your License Key textbox. If you do not have a license, you can generate an evaluation license by clicking on the generate a Jira trial license link. The evaluation license will grant you access to Jira’s full set of features for 1 month. After the evaluation period ends, you will lose the ability to create new issues, but you can still access your data:

Figure 1.15 – Jira configuration step 4

5. Now, you must set up the administrator account for Jira. It is important that you keep the account details somewhere safe and do not lose the password. Since Jira only stores the hashed value of the password instead of the actual password itself, you will not be able to retrieve it. Fill in the administrator account details and click on Next:

Figure 1.16 – Jira configuration step 5

Important note

This account is important, and it can help you troubleshoot and fix problems later on. Do not lose it!

6. Next, you must set up your email server details. Jira will use the information configured here to send out notification emails. Notifications are a very powerful feature in Jira and one of the primary ways Jira communicates with users. If you do not have your email server information handy, you can skip this step for now by selecting the Later option and clicking on Finish. You can configure your email server settings later, as you will see in Chapter 8, Emails and Notifications:

Figure 1.17 – Jira configuration step 6

Congratulations! You have completed your Jira setup. You should now see the welcome page, and be automatically logged in as the administrator user you created in Step 5. On the welcome page, you will need to set up a few user preferences, such as the default language and profile picture. Follow the onscreen prompts to set up the account. Once you are done, you should be presented with the options to create a sample project, a new project from scratch, or import project data from other sources, as shown in the following screenshot:

Figure 1.18 – Jira welcome page

With that, Jira is fully configured. We will cover the various features and things you can do with it later in this book, but for now, we will look at some additional management and configuration options for Jira, starting with how to start and stop Jira as a service.

Starting and stopping Jira

Since we used Windows Installer, Jira is installed as a Windows service. Therefore, you can start, stop, and restart it via the Windows Services console. In the Services console, look for Atlassian Jira. Here, you will be able to stop and start the application, as shown in the following screenshot:

Figure 1.19 – Windows Services

If you installed Jira using the archive options, you can start and stop Jira using the scripts provided in the JIRA_INSTALL\bin directory, which are start-jira.sh and stop-jira.sh for Linux, and start-jira.bat and stop-jira.bat for Windows.

Now that we know how to start and stop Jira, let’s look at some of the additional configurations, such as allocating memory.

The post-installation configuration steps are optional, depending on your needs and environment. If you set up Jira for evaluation purposes, you probably do not need to perform any of the following steps, but it is always good practice to be familiar with these as a reference.

You will need to restart Jira after making the changes that will be discussed in the next section.

Increasing Jira’s memory

The default memory setting for Jira is usually sufficient for a small to medium-sized deployment. As Jira’s adoption rate increases, you will find that the amount of memory allocated by default is no longer enough. If Jira is running as a Windows service, as we described in this chapter, you can increase the memory as follows:

1. Find the service name for Jira. You can do this by going to the Windows Services console and double-clicking on the Atlassian Jira service. The service name will be shown in the General tab; for example, JIRA150215215627.
2. Open a new Command Prompt and change the current working directory to the JIRA_INSTALL\bin directory.
3. Run the following command by substituting the actual service name for Jira:

           tomcat8w //ES//<JIRA Windows service name>

4. Select the Java tab, update the Initial memory pool and Maximum memory pool sizes, and click on OK:

Figure 1.20 – Jira memory settings

5. Restart Jira to apply the change.

If you are not running Jira as a Windows service, you need to open the setenv.bat file (for Windows) or the setenv.sh file (for Linux) in the JIRA_INSTALL\bin directory. Then, locate the following lines:

set JVM_MINIMUM_MEMORY="384m"
set JVM_MAXIMUM_MEMORY="768m"

Change the value for the two parameters and restart Jira. Normally, 4 GB (4,096 MB) of memory is enough to support a fairly large instance of Jira used by hundreds of users.

The initial memory pool or JVM_MINIMUM_MEMORY parameter determines the amount of memory Jira will start with. Usually, the smaller the amount, the faster Jira will start up. The maximum memory pool or JVM_MAXIMUM_MEMORY parameter determines the maximum amount of memory Jira can use. If the two values are not the same, Jira will start up with the minimum amount of memory and grow to the maximum as more and more users start to use Jira.

Important note

Make sure that you have sufficient physical RAM available before allocating instances to Jira.

Changing Jira’s port number and context path

As part of the installation process, the installation wizard prompted us to decide which port Jira should listen to for incoming connections. If you accepted the default value, then this will be port 8080. If you change your mind and want to change this setting later, you can do so by locating and opening the server.xml file in a text editor in the JIRA_INSTALL/conf directory. Let’s examine the relevant contents of this file:

<Server port="8005" shutdown="SHUTDOWN">

This preceding line specifies the port for the command to shut down Jira. By default, it is port 8005. If you already have an application that is running on that port (for example, another instance of Jira), you need to change this to a different port. The following line specifies which port Jira will be running on:

<Connector port="8080" protocol="HTTP/1.1">

By default, Jira will be running on port 8080. If you already have an application that is running on that port, or if the port is unavailable for some reason, you need to change it to another available port. The following line allows you to specify the context that Jira will be running under:

<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false" useHttpOnly="true">

By default, the value is empty, which means Jira will be accessible from http://hostname:portnumber. If you decide to specify a context, the URL will be http://hostname:portnumber/context. In our example, Jira will be accessible from http://localhost:8080/jira.

Configuring HTTPS

By default, Jira runs with a standard, non-encrypted HTTP protocol. This is acceptable if you are running Jira in a secured environment, such as an internal network. However, if you plan to open up access to Jira over the internet, you will need to tighten up security by encrypting sensitive data, such as usernames and passwords that are being sent, by enabling HTTPS (HTTP over SSL).

For a standalone installation, you will need to do the following, in order:

1. Obtain and install a certificate
2. Enable HTTPS on your application server (Tomcat)
3. Redirect traffic to HTTPS

First, you need to get a digital certificate. This can be obtained from a certification authority, such as VeriSign (CA certificate), or a self-signed certificate that’s been generated by you. A CA certificate will not only encrypt data for you but also identify your copy of Jira to the users. A self-signed certificate is useful when you do not have a valid CA certificate and you are only interested in setting up HTTPS for encryption. Since a self-signed certificate is not signed by a certification authority, it is unable to identify your site to the public and users will be prompted with a warning that the site is untrusted when they first visit it. However, for evaluation purposes, a self-signed certificate will suffice until you can get a proper CA certificate.

For this exercise, we will create a self-signed certificate to illustrate the complete process. If you have a CA certificate, you can skip the following steps:

1. Java comes with a handy tool for certificate management, called keytool, which can be found in the JIRA_INSTALL\jre\bin directory if you are using the installer package. If you are using your own Java installation, then you can find it in JAVA_INSTALL\bin.
2. To generate a self-signed certificate, run the following commands from Command Prompt:

   keytool -genkey -alias tomcat -keyalg RSA
   keytool -export -alias tomcat -file file.cer

3. This will create a KeyStore (if one does not already exist) and export the self-signed certificate (file.cer). When you run the first command, you will be asked to set the password for the KeyStore and Tomcat. You need to use the same password for both. The default password is changeit. You can specify a different password of your choice, but then you have to let Jira/Tomcat know, as we will see later.

Now that you have your certificate ready, you need to import it into your trust store for Tomcat to use. Again, you will use the keytool application in Java:

keytool -import -alias tomcat -file file.cer
JIRA_INSTALL\jre\lib\security\cacerts

This will import the certificate into your trust store, which can be used by JIRA/Tomcat to set up HTTPS.

To enable HTTPS on Tomcat, open the server.xml file in a text editor from the JIRA_INSTALL/conf directory. Locate the following configuration snippet:

<Connector port="8443" maxHttpHeaderSize="8192" SSLEnabled="true"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS"     useBodyEncodingForURI="true"/>

This enables HTTPS for Jira on port 8443. If you have selected a different password for your KeyStore, you will have to add the following line to the end of the preceding snippet before the closing tag:

keystorePass="<password value>"

The last step is to set up Jira so that it automatically redirects from a non-HTTP request to an HTTPS request. Find and open the web.xml file in the JIRA_INSTALL/atlassian-jira/WEB-INF directory. Then, add the following snippet to the end of the file before the closing </web-app> tag:

<security-constraint> <web-resource-collection> <web-resource-name>all-except-attachments</web-resource-name> <url-pattern>*.js</url-pattern> <url-pattern>*.jsp</url-pattern>
    <url-pattern>*.jspa</url-pattern>
    <url-pattern>*.css</url-pattern>
    <url-pattern>/browse/*</url-pattern>
  </web-resource-collection>
  <user-data-constraint>
    <transport-guarantee>CONFIDENTIAL</transport-guarantee>
  </user-data-constraint>
</security-constraint>

Now, when you access Jira with a normal HTTP URL, such as http://localhost:8080/jira, you will be automatically redirected to its HTTPS equivalent – that is, https://localhost:8443/jira.

So far, our Jira instance is running in standalone mode, which means it is serving all the requests by itself and is not yet cluster-enabled. Some of the main benefits of running Jira in a cluster are as follows:

• Improved performance at scale: By running a cluster with multiple nodes, Jira’s ability to serve concurrent user requests is greatly improved, leading to better response time and overall user satisfaction.
• High availability and failover: With multiple nodes running in a cluster, if any individual node becomes unavailable for any reason, other nodes within the cluster can continue to serve your users, thus avoiding downtime.
• Zero-downtime upgrade: Usually, when you need to upgrade Jira, there will be downtime involved in the process. When running a Jira cluster, you can upgrade each node individually at a time so that other nodes in the cluster can continue to serve your users.

To configure Jira to run in a cluster, you must do the following:

1. Create a shared file home directory for both nodes to access.
2. Add cluster configuration to our current Jira instance.
3. Add another Jira instance to be the second node in our cluster. Technically, you can have a single node cluster, but for this exercise, we will add another node to the cluster so that you can see the cluster in action.
4. Add and configure a load balancer to distribute incoming traffic to both nodes.

Now that we know what we need to run Jira in a cluster, let’s start preparing!

Preparing for clustering

The first step in enabling clustering is to prepare the hardware required. For a Jira cluster, you will have the following components:

• Load balancer: This can be any load balancer that supports session affinity (sticky sessions), such as Apache and nginx.
• Jira instance node: This will contain separate Jira instances that will be part of the cluster.
• Database: This is the same database you are using for your standalone deployment. Note that since all Jira nodes will be sharing the same database, the in-memory H2 database will not work in a cluster.
• Shared file drive: The Jira cluster needs to have a shared home directory that all Jira nodes can read and write to.

Ideally, each component listed previously should be running on its own server, so for a two-node cluster, you will need a minimum of three servers and a shared network drive. You can run multiple Jira nodes on the same server, but you should only do this for evaluation purposes, as it diminishes the benefits of having a cluster.

When preparing servers for the Jira nodes, you need to ensure the following:

• All node servers are located in the same data center or region (for cloud vendors such as AWS and Azure)
• You have the same software and hardware specifications, including memory, operating system, and Java version
• All nodes are running the same version of Jira
• The nodes have been configured to be in the same timezone

Creating JIRA_SHARED_HOME

The first step is to create a new directory where the cluster can store its data files. We will refer to this directory as JIRA_SHARED_HOME. This can be a network drive that allows all Jira nodes to read from and write to. Copy over the following directories from your standalone Jira instance’s JIRA_HOME directory to the new shared directory:

• data
• plugins
• logos
• import
• export
• caches

Enabling clustering

The second step is to enable clustering for your first Jira node. This is done by adding a new cluster.properties file to its local JIRA_HOME directory.

1. Shut down your Jira standalone instance.
2. Create a new file called cluster.properties.
3. Add the following lines to the files:

   # This ID must be unique across the cluster
   jira.node.id = node1
   # The location of the shared home directory for all Jira nodes
   jira.shared.home = /location/to/the/shared/jira_cluster_home
   # The following lines are needed if you want to run multiple nodes on the same server
   ehcache.listener.hostName=localhost
   ehcache.listener.port=40001
   ehcache.object.port = 40021

4. Start Jira.

Adding a node to the load balancer

With the first cluster node up and running, we can add another node. We need to add this node to the load balancer so that it can start routing traffic to it. The exact configuration will differ, depending on what you use for the load balancer. The following is an example using Apache:

<Proxy balancer://jiracluster>
  # Jira node 1
  BalancerMember http://jira1.internal.atlassian.com:8080 route=node1
  # Jira node 2, add this when we have the 2nd node up and running
  # BalancerMember http://jira2.internal.atlassian.com:8080 route=node2
  # Load Balancer Settings
  ProxySet lbmethod=byrequests
  ProxySet stickysession=JSESSIONID
</Proxy>

Note that for Apache, you will need to enable the proxy_balancer_module module.

Adding new nodes to the cluster

To add a new node to the cluster, follow these steps:

1. Copy over the JIRA_HOME directory from our existing Jira instance to the new node server.
2. Install a new Jira instance on the new server.
3. Edit the cluster.properties files and change the jira.node.id value.
4. Add the new node to the load balancer.
5. Start the new Jira node.

If you are running the second node on the same server, you will also need to change the port numbers for ehcache.listener.port and ehcache.object.port in the cluster.properties file, and the port numbers in the server.xml file, as mentioned in the Changing Jira’s port number and context path section.

And with this, you should have a two-node Jira cluster up and running. Now, if you log into Jira and go to Administration | System | Clustering, you should see both nodes listed, with the node currently serving you highlighted in bold, as shown here:

Figure 1.21 – Cluster nodes in Jira

On this page, you can see all the nodes in your cluster and their status. This is very useful to help you troubleshoot your cluster if a node becomes unresponsive or is under heavy load.

As mentioned earlier, when you are running Jira in a cluster, you can perform a zero-downtime upgrade, also known as a rolling upgrade. With a zero-downtime upgrade, you can upgrade each node in the cluster one at a time. When a node is being upgraded, other nodes in the cluster will continue serving your users, so they will not experience any downtime.

Performing a rolling upgrade consists of the following steps:

1. Put Jira into Upgrade mode. This will allow the Jira cluster to have nodes with different versions running at the same time.
2. Upgrade each node in the cluster one at a time.
3. Finalize the upgrade once all the nodes have been upgraded.

We will start by putting Jira into Upgrade mode:

1. Log into Jira as an administrator.
2. Browse to Administration | Applications | Jira upgrades.
3. Click Put Jira into upgrade mode:

Figure 1.22 – Zero-downtime upgrade

Once Jira has been put into Upgrade mode, you can shut down a node in the cluster and upgrade it. After a node has been upgraded, you can restart it and repeat this process for other nodes in the cluster.

After you have upgraded all the nodes in the cluster, you need to finalize the upgrade by doing the following:

1. Browsing to Administration | Applications | Jira upgrades.
2. Clicking Finalize upgrade.

Once you have clicked on Finalize Upgrade, this will complete the upgrade process for your cluster. By doing a rolling upgrade like this, you can upgrade your entire cluster without disrupting your users with downtime.

Jira is a powerful, yet simple, application, as reflected in its straightforward installation procedures. You have a wide variety of options available so that you can choose how you would like to install and configure your copy. You can mix and match different aspects, such as operating systems and databases, to best suit your requirements. You can run a standalone deployment to get started, and later turn it into a cluster as the adoption of Jira grows in your organization.

In the next chapter, we will start to explore various aspects of Jira, starting with projects, and how you can use Jira to manage them for business teams.