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

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.

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.

Due to a known issue, you must upgrade UPM to version 2.17.4 before using JIRA Data Center.  This will be fixed in JIRA Data Center 6.3.1.

2. Connect your existing JIRA instance to your load balancer

Please perform your own load balancer testing based upon on what logic you use to route requests. Note that the easiest way to see which node a browser is connected to is in the footer.

3. Set up the JIRA file storage location on a separate server 

In this step, you need to set up a shared home directory that is writable by the JIRA instance and any future nodes, plus a "local home" directory for the exclusive use of this node.

You may already have your JIRA home directory on a networked file system, in which case you need to:

  • Ensure that directory can be read and written by other potential nodes
  • Update your atlassian-jira/WEB-INF/classes/jira-application.properties file to point to a new local home directory that will not be used by the other nodes; this directory can either be truly local or located somewhere else on a networked file system
  • Copy into this new location to the dbconfig.xml file

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

  1. Set up the following on your existing JIRA instance:
    • 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 forall JIRA nodes
      jira.shared.home = /net/mynfsserver/jira_shared_home

      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
  2. Ensure the Base URL configured in JIRA is the URL of the front end proxy / load balancer.
  3. If you use the Apache load balance, configure httpd

    Configuration example...

    If you use the Apache load balancer, configure httpd similarly to a standard reverse proxy, but with the addition of the mod_proxy_balancer configuration. Add a configuation block similar to this exampleat the end of http.conf:

    <VirtualHost *:80>
            ProxyRequests off
     
            ServerName MyCompanyServer
     
            <Proxy balancer://jiracluster>
                    # JIRA node 1
                    BalancerMember http://jira1.internal.atlassian.com:8080 route=node1
                    # JIRA node 2
                    BalancerMember http://jira2.internal.atlassian.com:8080 route=node2
     
                    # Security "we aren't blocking anyone but this the place to make those changes
                    Order Deny,Allow
                    Deny from none
                    Allow from all
     
                    # Load Balancer Settings
                    # We are not really balancing anything in this setup, but need to configure this
                    ProxySet lbmethod=byrequests
                    ProxySet stickysession=JSESSIONID
            </Proxy>
     
            # Here's how to enable the load balancer's management UI if desired
            <Location /balancer-manager>
                    SetHandler balancer-manager
     
                    # You SHOULD CHANGE THIS to only allow trusted ips to use the manager
                    Order deny,allow
                    Allow from all
            </Location>
     
            # Don't reverse-proxy requests to the management UI
            ProxyPass /balancer-manager !
            # Reverse proxy all other requests to the JIRA cluster
            ProxyPass / balancer://jiracluster/
            ProxyPreserveHost on
    </VirtualHost>

Verify that JIRA works correctly in the cluster by accessing JIRA through the load balancer and creating an issue with an attachment. Then check that this issue and attachment can be viewed/edited by another web browser through the load balancer.

5. Add a new JIRA node to the cluster

  1. Install a new standalone JIRA instance by using one of the methods below. During the intallation, configure this new instance to use the same database and context path as the existing node(s). 
    1. Take a native backup of the original JIRA instance and copy it to the new node, then change the node ID from node1 to node2, or
    2. Perform a fresh install of JIRA 6.3 on the new node. Configure it by setting the home directory and editing/copying the dbconfig.xml and cluster.properties files as required before starting JIRA for the first time on the new node.
    3. In either case DO NOT import any data into the new node.
  2. Configure it for clustering (as explained in Step 3). Ensure that its local home directory points to a different directory than the other nodes.

You can verify that data is correctly being synced to the new node by accessing the node directly and viewing the issue and attachment created earlier. 

6. Connect this new node to the load balancer

Atlassian assumes you or your IT department already knows how to do this. Please let us know if this is not the case.

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. To find out which node a user is connected to simply check the cookie for the apache load balancer config.

Repeat steps 5 and 6 for each node.

 

Cluster.properties file parameters

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

ParameterRequiredDescription/value
jira.node.idYesThis unique ID must match the username and the BalancerMember entry in the Apache config
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 - 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.hostNameNoThe 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 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.socketTimeoutMillisNoBy default this is set to the Ehcache default

If you set ehcache.peer.discoveryautomatic  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.

Last modified on Sep 3, 2014

Was this helpful?

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