Installing JIRA Data Center

These instructions are applicable for installing JIRA Software Data Center or JIRA Service Desk Data Center on your own hardware. 

If you're looking to host JIRA Data Center externally, see:

Learn more about what Jira Software Data Center and Jira Service Desk Data Center provide on our website.

Before you begin

Before you install JIRA Data Center, you need to answer a few questions.

What is JIRA Data Center?

Tell me more...

We’ve created a handy quick start guide to help you understand what’s going on with DC, and what you need to do to get it up and running in no time!

Take a look at Quick start for JIRA Data Center.

How do I get it?
Tell me more...

You'll need two things to get started – an installer, and a license.

If you're installing JIRA from scratch, you'll first need to apply the evaluation license so make sure you create it.

What are the prerequisites?

Tell me more...

Supported platforms

Supported operating systems, databases, etc., are the same as for the Server installation, and you can see them here: Supported platforms.

Node requirements

Requirements specific to Data Center include requirements for nodes that create the cluster:

  • Each node is a separate machine (physical or virtual). They don't need to be identical, but should be as similar as possible for consistent performance.
  • All nodes are running the same version of JIRA. You'll be copying JIRA from one node to another, so this shouldn't be a problem. They use the same timezone, and have the current time synced. You can use ntpd to set this up.
  • All nodes share a common database, also installed on a separate machine.
  • All nodes can access the shared home directory. You can set it up using NFS, or a similar solution. We'll mention it in this guide.
Do I need a load balancer?
Tell me more...

Yes. JIRA Data Center relies on a load balancer to balance the traffic between the nodes, and this guide assumes that you already have one set up. You can use a load balancer of your choice, just make sure it meets these requirements:

  • Supports "cookie based session affinity", also known as "sticky sessions".
  • Can route HTTP/HTTPS traffic to one of the available nodes.
  • Can determine whether a node is available or not, and route requests to other nodes if needed.
  • All Atlassian applications and other REST clients must access your nodes through the load balancer.

Or you can just turn your proxy into a load balancer.

Many bigger installations of JIRA already have a reverse proxy configured, and many reverse proxies can do load balancing as well. We've provided some examples on how to use your proxy as a load balancer. See Load balancer examples.

1. Install or upgrade your JIRA instance

JIRA Data Center is available for JIRA 7.0, or later. If you're not on this version yet, install or upgrade your JIRA instance. 

JIRA installation and upgrade guide

Few things to know about:

  • If you're installing your instance from scratch, generate a non-Data Center evaluation license at the setup stage, and update to the Data Center license when you're adding the cluster.properties file at step 3.
  • If you're upgrading your instance, update to the Data Center license when you're adding the cluster.properties file at step 3.

2. Set up the shared directory

You'll need to create a remote directory that is readable and writable by all nodes in the cluster. There are multiple ways to do this, but the simplest is to use an NFS share.

  1. Create a remote directory, accessible by all nodes in the cluster, and name it e.g. sharedhome
  2. Stop your JIRA instance.
  3. Copy the following directories from the JIRA local home directory to the new sharedhome directory (some of them may be empty).

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

3. Configure your existing JIRA instance to work in a cluster

  1. In the JIRA local home directory, create a cluster.properties file, with contents as follows:

    Example cluster.properties file:

    # 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 = /data/jira/sharedhome

    For more information and some additional parameters, see Cluster.properties file parameters.

  2. Start your instance, and apply the Data Center license.

4. Add the first node to the load balancer

The load balancer distributes the traffic between the nodes. If a node stops working, the remaining nodes will take over its workload, and your users won't even notice it.

  1. Add the first node to the load balancer.
  2. Restart the node, and then try opening different pages in JIRA. If the load balancer is working properly, you should have no problems with accessing JIRA.

5. Add the remaining nodes to the cluster

  1. Copy the JIRA installation directory and the local home directory from the first node to this new node.

  2. Ensure the new node can access (read and write) the shared home directory.

  3. Edit the cluster.properties file, and change the node ID. All node IDs must be unique among nodes.

  4. Start JIRA. It will read the configuration from the shared home directory, and start without any extra setup.

  5. Take a look around the new JIRA instance. Ensure that issue creation, search, attachments, and customizations work as expected.

  6. If everything looks fine, you can configure your load balancer to start routing traffic to the new node. Once you do this, you can make a couple of changes in one JIRA instance to see if they're visible in other instances as well.

While adding your nodes to the cluster, you can check their status by going to  > System > System info. Your nodes will be listed in the Cluster nodes section.

Cluster.properties file parameters

In addition to the required parameters, the cluster.properties file allows you to configure some additional options, mostly related to EhCache.

Tell me more...
ParameterRequiredDescription/value
jira.node.id YesThis unique ID must match the username and the BalancerMember entry in the Apache configuration.
jira.shared.homeYesThe location of the shared home directory for all JIRA nodes.
ehcache.peer.discoveryNo

Describes how nodes find each other:

default – JIRA will automatically discover nodes (recommended)
automatic – JIRA will use the EhCache's multicast discovery. This is the historical method used by EhCache, but it can be difficult to configure, and is not recommended by Atlassian.

If you choose automatic...

If you set ehcache.peer.discovery = automatic then you need to set the following parameters:

  • ehcache.multicast.address

  • ehcache.multicast.port

  • ehcache.multicast.timeToLive

  • ehcache.multicast.hostName

For more info on these parameters, see Ehcache documentation.

ehcache.listener.hostNameNo

The hostname of the current node for cache communication. JIRA Data Center will resolve this this internally if the parameter isn't set.
If you have problems resolving the hostname of the network you can set this parameter.

ehcache.listener.portNo

The port that the node is going to be listening to (default is 40001).

If multiple nodes are on the same host, or if this port is unavailable, you might need to set this parameter manually.

ehcache.object.portNo

The port on which the remote objects bound in the registry receive calls. Make sure you also open this port on your firewall.

We recommend that you specify this parameter, as otherwise a random free port will be used.

ehcache.listener.socketTimeoutMillisNoBy default, this is set to the EhCache default.

Security

To secure your application, use a firewall or network segregation (or both) to ensure that only permitted nodes connect to Jira Data Center's Ehcache RMI ports. If you use a firewall, you must open ports in the firewall between nodes and the cache, or else you may see cache replication issues. The two default Ehcache RMI ports are 40001 and 40011. 

Monitoring the health of your Data Center

Now that you got your Data Center up and running, we recommend that you keep monitoring its health right from the start. This will help you keep any problems from getting bigger and messing with your work, and you'll always know what's going on in the cluster. 

JIRA Data Center is equipped with a set of health checks tools that let you monitor the whole cluster and each node individually, including all important settings. To access the health check tools, go to  > System > Support Tools. All health checks are listed in the Instance health tab. 

Last modified on Feb 3, 2021

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.