In this chapter, we will start by providing a high-level overview of Jira, the various products that run on top of the platform, and then introduce Jira Data Center. After that, we will examine the various deployment options and system requirements for hosting Jira Data Center yourself. Finally, we will get our hands dirty by installing our very own Jira Data Center from scratch, both as a standalone and a clustered deployment.
In this chapter, we will cover the following topics:
By the end of the chapter, you will have learned about the Jira platform and the new Data Center product. You will also learn about the system requirements to install Jira, and how a Jira cluster works. Finally, you will have your own Jira instance up and running.
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:
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:
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.
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:
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.
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.
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.
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.
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:
Database |
Support Status |
MySQL |
MySQL 5.7, 8.0 Note that both MariaDB and PerconaDB are not supported |
PostgreSQL |
PostgreSQL 10, 11, 12 |
Microsoft SQL Server |
SQL Server 2016, 2017, 2019 |
Oracle |
Oracle 12c R2, 18c, 19c This requires the JDBC 19.3 (ojdbc8) driver |
Azure SQL | |
Amazon Aurora |
PostgreSQL 10, 11, 12 |
H2 |
This is bundled with the standalone distribution, for evaluation purposes only |
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:
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.
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:
Note
At the time of writing, the latest version of Java 8 is JDK 8 Update 321.
Figure 1.3 – The JAVA_HOME environment variable
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:
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:
Let’s begin by installing Jira!
Before we install Jira, here are two important directories we need to mention:
We will be referring to those two directories throughout this book. Now, on to the installation. There are generally two steps involved:
Let’s get started.
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):
Figure 1.4 – Jira installation step 1
Figure 1.5 – Jira installation step 2
Figure 1.6 – Jira installation step 3
Figure 1.7 – Jira installation step 4
Figure 1.8 – Jira installation step 6
Figure 1.9 – Jira installation step 7
Figure 1.10 – Jira installation step 8
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.
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:
Figure 1.12 – Jira configuration step 1
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.
Figure 1.14 – Jira configuration step 3
Figure 1.15 – Jira configuration step 4
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!
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.
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_INSTALLin 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.
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:
tomcat8w //ES//<JIRA Windows service name>
Figure 1.20 – Jira memory settings
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_INSTALLin 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.
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.
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:
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:
keytool -genkey -alias tomcat -keyalg RSA
keytool -export -alias tomcat -file file.cer
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_INSTALLjrelibsecuritycacerts
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:
To configure Jira to run in a cluster, you must do the following:
Now that we know what we need to run Jira in a cluster, let’s start preparing!
The first step in enabling clustering is to prepare the hardware required. For a Jira cluster, you will have the following components:
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:
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:
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.
# 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
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.
To add a new node to the cluster, follow these steps:
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:
We will start by putting 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:
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.
18.119.125.135