Installing JIRA Data Center

These instructions are applicable for installing JIRA Software Data Center or JIRA Service Desk Data Center on your own hardware. You can also install JIRA Software Data Center or JIRA Service Desk Data Center in Amazon Web Services.

Before you start

Before you install JIRA Data Center, review this prerequisite information:

• Understand how Jira Data Center documentation 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.
  • Nodes must be configured to have unrestricted port access to each other.
• Install and configure a load balancer of your choice:
  
  • The load balancer must support "cookie based session affinity", (also known as "sticky sessions").
• You need a JIRA Data Center license. You'll need this to allow JIRA to use the clustering capabilities. To get one you should either:
  • Purchase a JIRA Software Data Center or JIRA Service Desk Data Center license, or
  • Create an evaluation license.

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.

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 7.0 or later

See JIRA applications installation guides or the JIRA applications upgrade guides.

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

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. We recommend using a UNC file path to your storage location.

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
  • caches
    

$ cp -R /path/to/jira-local-home/{data,plugins,logos,import,export,caches} /data/jira/sharedhome

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

Set up the following on your existing JIRA instance:

1. Stop your instance.

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

3. Start your instance, and install your Data Center license.

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.

<VirtualHost *:80>
        ProxyRequests off
 
        ServerName MyCompanyServer
 
        <Proxy balancer://jiracluster>
                # JIRA node 1
                BalancerMember http://jira1.internal.atlassian.com:8080 route=node1
                # JIRA node 2  Commented pending node installation
                # 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>

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.

Security

Ensure that only permitted cluster nodes are allowed to connect to a JIRA Data Center instance's ehcache RMI port, which by default is port port 40001, through the use of a firewall and/or network segregation. Not restricting access to the ehcache RMI port could result in the compromise of a JIRA Data Center instance.

Cluster.properties file parameters

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

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.