Installing JIRA Data Center

Before you start:

Before you install JIRA Data Center, please review this pre-requisite information:

  • Understand how JIRA Data Center works.
  • Understand the node requirements:
    • Each JIRA node must run on its own machine (physical or virtual), with a separate machine for the shared services. The shared services machine must be accessible by each node.
    • Normal JIRA supported platforms and requirements apply to each node.
    • Each node does not need to be identical, but for consistent performance we recommend they are as close as possible.
    • Nodes must run the exact same JIRA version and must be located in the same data center.
    • Nodes must be configured with the same timezone and keep the current time synchronized. Using ntpd or some similar service is a good way to arrange this.
  • Install and configure a load balancer of your choice:
    • The load balancer must support "cookie based session affinity".  Also known as "sticky sessions".

You can optionally cluster the load balancer, database, and shared file systems.

After you install JIRA Data Center or add a new node to your environment, use the health check tools to check that your instance is configured and operating correctly.

This page:

Installing JIRA Data Center

This illustration shows the general method of installing a JIRA clustered instance:

This install guide assumes that you already have a JIRA instance, already have a load balancer, and are able to set up a network file share system.

Before upgrading from an earlier version of JIRA, back up your data. Refer to Automating JIRA Backups.

1. Upgrade your JIRA instance to 6.3 or later

See JIRA Installation and Upgrade Guide.

JIRA clustering is only available from 6.3 onwards and you must purchase a JIRA Data Center license to use the clustering functionality of JIRA Data Center. Please contact our sales team for information about purchasing a JIRA Data Center license.


2. Set up the JIRA file storage location on shared storage

In this step, you need to set up a shared home directory that is writable by the JIRA instance and any future nodes.

There are multiple ways to do this, but the simplest is to use an NFS share. The mechanics of setting one is unique from installation to installation and is outside the scope of this document.

Assuming that the final mount point for this shared storage location is /data/jira/sharedhome :

  • Ensure that directory can be read and written by other potential nodes
  • Copy the following directories into /data/jira/sharedhome: (some of them may be empty)
    • data
    • plugins
    • logos
    • import
    • export

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

Set up the following on your existing JIRA instance:

  1. Put a cluster.properties file in the local JIRA home directory, with contents as follows:
  Expand for example

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

See Cluster.properties file parameters for more information.

  • If using the Apache load balancer, set the Apache node name by appending the following setting to the same variable (replacing node1 with the node name used in the load balancer configuration):
    • -DjvmRoute=node1

4. Add the first node to your load balancer

JIRA Data Center relies on a load balancer to balance traffic between the nodes. Many larger installations of JIRA already have a reverse proxy configured, and many reverse proxies have the ability to perform load balancing as well. We've provided a sample Apache httpd configuration to serve as an example, but please check with your proxy vendor for specific information.

  Sample httpd configuration with mod_balancer

After adding JIRA to the load balancer, ensure that basic functionality is working after restarting the JIRA instance by navigating to the instance, logging in, and noting any broken links or malfunctioning JIRA functionality.

Be sure to check that the base server URL is configured properly (to the load balancer public URL).

5. Add a new JIRA node to the cluster

  1. Copy the JIRA installation directory to a new host. Atlassian recommends that your configuration deviates from the first installation as little as possible to ease the burden of documentation and deployment (e.g. Installation paths, users, file permissions, etc).
  2. Ensure that the new host can access the shared home directory (e.g. ensure that you can read the contents of the shared JIRA directory and have write access to it)
  3. Copy the local home directory from the first node to this new node.
  4. Alter the cluster.properties file to reference the new node id. All node ids must be unique among nodes.
  5. Start the new node and monitor for startup problems.
  6. Ensure that issue creation, search, attachments, and customizations work as expected.

6. Connect this new node to the load balancer

Verify that the new node is in the cluster and receiving requests by checking the logs on each node to ensure both are receiving traffic and also check that updates done on one node are visible on the other.

Repeat steps 5 and 6 for each node.

Cluster.properties file parameters

You can set the following parameters in the cluster.properties file:

Parameter Required Description/value
jira.node.id Yes This unique ID must match the username and the BalancerMember entry in the Apache config
jira.shared.home Yes The location of the shared home directory for all JIRA nodes
ehcache.peer.discovery No

Describes how nodes find each other:

default - JIRA will automatically discover nodes. Recommended
automatic - Will use EhCache's multicast discovery. This is the historical default method used by ehCache, but can be problematic for customers to configure and is no longer recommended by Atlassian for use with JIRA clustering

ehcache.listener.hostName No 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.port No

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

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

ehcache.listener.socketTimeoutMillis No By default this is set to the Ehcache default

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

Refer to the Ehcache documentation for more information on these parameters.

Was this helpful?

Thanks for your feedback!

11 Archived comments

  1. User avatar

    Gerardo Romero

    OK... Just checking... the other JIRA instance (new one) must have its own licences, right?

    10 Jul 2014
    1. User avatar

      Roy Krishna [Atlassian]

      Data Center requires a new license type, however each node in the cluster does not require it's own unique license.

      10 Jul 2014
  2. User avatar

    Tarun Sapra

    Am I right in understanding the following things -

    So the nodes always share the same database and filesystem and the incoming requests are directed using load balancers?

    What if we need another database so in case of multiple databases does the syncing between the database taken care of by the "JIRA data center" ?

     

    25 Jul 2014
    1. User avatar

      Randy Thomas

      Tarun,

      Yes the nodes all connect to the same database and shared filesystem (note that each node also stores certain files that are unique to the instance on its local file system). If you choose to replicate your database to eliminate the database as a single point of failure, the database vendor provides the technology to support that (e.g. syncing across database instances). For all intents and purposes, from the JIRA perspective, a replicated database looks and operates the same as a standalone database instance. 

      25 Jul 2014
  3. User avatar

    Rp Subhub

    JIRA will automatically discover nodes. Recommended

    How will JIRA do it?

    ecache.listener.hostName, ecache.listener.port

    Shouldn't it be "ehcache"?

    11 Aug 2014
  4. User avatar

    Graham Carrick [Atlassian]

    How will JIRA do it?

    Each node in the cluster heartbeats to the database and this heartbeat is used as a registry of the nodes in the cluster. This heartbeat includes the hostname or IP of the node which is then used for node to node communication. 

    Yes it should be ehcache, I'll correct that. 

    11 Aug 2014
  5. User avatar

    Matt Doar [ServiceRocket]

    Graham, is there any way to use Data Center without multicast traffic? This page seems to suggest it might be possible with ehcache.peer.discovery=default

    19 Sep 2014
  6. User avatar

    Graham Carrick [Atlassian]

    As of 6.3.3 JIRA Data Center does not require multicast. Multicast is only used for node discovery and only if that method for node discovery is set to automatic (instead of default). 

    24 Sep 2014
  7. User avatar

    Otto Ruettinger

    Hi sprint new,

    Raising a support request at support.atlassian.com will probably get this issue resolved faster than comments on this page. (smile)

    26 Jan 2015
  8. User avatar

    Preethi

    Will do. Thanks 

    26 Jan 2015
  9. User avatar

    Sridhar Nimmagadda

    Where would dbconfig.xml go ? I would assume it will be in global home , because its the same for all the nodes in the cluster

    22 Jul 2015
Powered by Confluence and Scroll Viewport