Cloud
Data Center and Server 8.19
Versions

Set up a Jira Data Center cluster

Running Jira Data Center in a cluster

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

Jira Data Center allows you to run a cluster of multiple Jira nodes, providing high availability, scalable capacity, and performance at scale. This guides walks you through the process of configuring a Data Center cluster on your own infrastructure. 

Not sure if clustering is right for you? Check out Running Jira Data Center in a cluster for a detailed overview.

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.
App compatibility

Apps extend what your team can do with Atlassian applications, so it's important to make sure that your team can still use their apps after migrating to Data Center. When you switch to Data Center, you'll be required to switch to the Data Center compatible version of your apps, if one is available. 

See Evaluate apps for Data Center migration for more information. 

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.

Set up and configure your 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
    • keys

Error: The XML content could not be parsed. There is a problem at line 1, column 1558. Parser message: Unexpected close tag </code>; expected </jira-install>. at [row,col {unknown-source}]: [1,1558]

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. 

Error: The XML content could not be parsed. There is a problem at line 1, column 1495. Parser message: Unexpected close tag </code>; expected </home-directory>. at [row,col {unknown-source}]: [1,1495]

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 (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.

Last modified on Oct 19, 2021

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.