Installing Jira Data Center

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

Other ways to install Jira Data Center

  • AWS - hassle-free deployment in AWS using our Quick Start
  • Azure - reference templates for Microsoft Azure deployment

Before you begin

Things you should know about when setting up your Data Center:

Supported platforms

See our Supported platforms page for information on the database, Java, and operating systems you'll be able to use. These requirements are the same for Server and Data Center deployments.

Requirements

To use Jira Data Center, you must:

To run Jira in a cluster, you must also:

  • Use a load balancer with session affinity and WebSockets support in front of the Jira cluster. Load balancer examples

  • Have a shared directory accessible to all cluster nodes in the same path (this will be your shared home directory). This must be a separate directory, and not located within the local home or install directory.

Terminology

In this guide we'll use the following terminology:

  • Installation directory: The directory where you installed Jira.

  • Local home directory: The home or data directory stored locally on each cluster node (if Jira is not running in a cluster, this is simply known as the home directory).

  • Shared home directory: The directory you created that is accessible to all nodes in the cluster via the same path.

Install Jira Data Center on a single node

If your organization doesn't need high availability or disaster recovery capabilities right now, you can install Jira Data Center without setting up a cluster.

To install Jira Data Center, without setting up a cluster, follow the instructions for Jira Server: 

The process is almost identical to an ordinary Jira Server installation, just be sure to enter your Data Center license.

Install Jira Data Center in a cluster

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

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 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. For Linux installations: We recommend that you increase the maximum number of open files. To do that, add the following line to <jira-install>/bin/setenv.sh:

    ulimit -n 16384


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

defaultJira will automatically discover nodes (recommended)
automaticJira 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 (default is 40011). Make sure you also open this port on your firewall.

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

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

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 26, 2020

Was this helpful?

Yes
No
Provide feedback about this article

In this section

Powered by Confluence and Scroll Viewport.