Setting up a JIRA Data Center test system on a single host

When it came to testing our new plugin DataQA for JIRA Data Center, there was basically two choices as per the documentation - setting up multiple VMs as individual JIRA nodes, and a load balancer/shared home/db machine. Or put everything on a single host.

Initially, we considered setting up multiple VMs to mimic a clustered environment - we use Dell Precision M6800 workstations, stacked with memory. These are great machines and can plough through serious work, including running multiple VMs (OK, the battery life is a little bit reduced when doing this). However - the single host setup would let us check that processing was occurring correctly, but simplify the cluster setup in terms of networking and file access.

So, we created an Ubuntu 14.04 VM with 8GB ram (we probably could have used less - an experiment for another day), and got to it. It turns out that the docs do not lead you through this process step by step, so we captured what we did below. We chose Ubuntu as it is usually very easy to get required components via apt. Your mileage may vary, and we accept absolutely no liability for the procedure below, nor do we guarantee its correctness, and it assumes a knowledge of Unix. But it works for us :-)

The Atlassian documentation above is a great starting point for some of the details, although copying the shared home then pointing a JIRA node at it did not work for us - the JIRA node wanted to create the shared home itself.

It is worth pointing out that a JIRA "node" in this context is a JIRA process running with a distinct port - basically a separate JIRA installation.

The basic process:

1. Get hold of an Ubuntu machine/VM.

2. Install required components (e.g. Postgres, pgadmin, Apache etc).

3. Install JIRA twice, in different places to create the "nodes". These will ultimately both point to a single Postgres database (created during the first node install) and a shared home directory. We do the first node as an Express install, but the second node as a Custom install, so we can configure its location and ports, and generally make sure that we get a separate instance.

4. Create a shared home, ensure that file permissions allow both JIRA processes to write to it.

5. Configure Apache as the load balancer.

6. Finish. As we are in the UK, have a cup of tea. It is likely that you may need one during the process as well.

In more detail....

Set up Ubuntu, Java, Postgres

First create an Ubuntu VM. Download from here, and point VMWare at the ISO. We used Ubuntu 14.04 and JIRA 6.4.12.

Once we are in, update apt.

sudo apt-get update

Install our first JIRA node, plus prerequisites.  The Dragons guide is excellent. The notes below cover Ubuntu specifics on installing Java and PostgreSQL. We logged in as root (sudo su -), as there are so many commands to do, and permissions to change. Sudo is generally best practice, however.

Install Java:

add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java8-installer
apt-get install oracle-java8-set-default

Postgres and pgadmin:

apt-get install postgresql postgresql-contrib
apt-get install pgadmin3

Setting up the "nodes"

Now we create the two JIRA installs, the first one using the Express method, the second one using the Custom method so that we can change the settings:

JIRA - node 1: Do an "Express install" for our first "node", and connect it to the local PostgreSQL DB. The application dir can be: /opt/atlassian/jira Its home dir can be: /var/atlassian/application-data/jira Normal ports: 8080, and 8005 for "control". Doing this installation will also have the effect of creating a JIRA user. Once installed, stop this JIRA node:

/etc/init.d/jira stop

JIRA - node 2: Do a "Custom install". We want a different installation location and ports from the first node. We will be using the database setup for node 1, however. The application dir can be: /opt/atlassian/jira1 Its home dir can be: /var/atlassian/application-data/jira1 Ports: 8081, 8006 Once installed, stop this JIRA node as well:

/etc/init.d/jira1 stop

A side effect of the second install will be to create a jira1 user and group. This is what this node will run under. We could change the init file so that both processes would run as the jira user, but we left this as is, as all the other files would have to be chowned appropriately.

Both nodes will ultimately need read write access to a shared home. They will also both share the database.

Whilst the nodes are both stopped, now we can set up the sharing. They are currently running as different users. We added the jira1 user to the jira group, and then ensured that all files were writable by the jira group. The id command will show you whether this worked.

Shared home setup

If these permissions aren't correct you can get a server locked error, and errors in the log file. The jira documentation suggests that you can just copy the contents of the first node's home directory to the second one. Let's go.

As root:

cd /var/atlassian/application-data
mkdir sharedhome
chown jira sharedhome
chgrp jira sharedhome
chmod 775 sharedhome

Copy the shared home files as per the jira documentation.

su jira
cp -R jira/{data,plugins,logos,import,export} sharedhome

You should end up with this - note the Jira group permission on sharedhome:

bdq@ubuntu:/var/atlassian/application-data$ ls -l
total 12
drwx------ 12 jira  root 4096 Dec 10 15:56 jira
drwx------ 10 jira1 root 4096 Dec 10 15:56 jira1
drwxrwxr-x 10 jira  jira 4096 Dec 10 16:34 sharedhome 

Shared DB setup

Both nodes need to be able to access the db. Copy (or link) the dbconfig.xml created when you installed the first node, and use it for the second note. Make sure that the second node can access it.

cd /var/atlassian/application-data
cp jira/dbconfig.xml jira1
chown jira1 jira1/dbconfig.xml

Cluster.properties file setup

One of these is required for each node, giving it information about the cluster. Ensure that there are no trailing spaces on "sharedhome". Otherwise, JIRA will attempt to create a directory with this name. This results in a locked website, and log entries which suggest that it wants write access to the application-data directory (and if given these permissions it will create a "sharedhome " directory. The files should look like the following - note that the jira.node.id and listener ports are different. Ensure that the files are accessible by the jira and jira1 users.

# 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=/var/atlassian/application-data/sharedhome
ehcache.listener.hostName=localhost
ehcache.listener.port=40001




root@ubuntu:/var/atlassian/application-data# cat jira1/cluster.properties
# This ID must be unique across the cluster
jira.node.id = node2
# The location of the shared home directory for all JIRA nodes
jira.shared.home = /var/atlassian/application-data/sharedhome
ehcache.listener.hostName=localhost
ehcache.listener.port=40002

Setenv.sh setup for each node

As per the documentation we have to change the setenv.sh file for each node, to provide a -DjvmRoute setting, and tell the node to be clustered. This can be done as root for both nodes.

cd /opt/atlassian

Edit the file for node 1. Ensure that the JVM_EXTRA_ARGS line looks like this for the node 1 setenv.sh file.

vi jira/bin/setenv.sh
..
JVM_EXTRA_ARGS="-XX:+PrintGCDateStamps -XX:-OmitStackTraceInFastThrow -Datlassian.cluster.scale=true -DjvmRoute=node1"

Repeat for node, but ensure the route is set to node2.

JVM_EXTRA_ARGS="-XX:+PrintGCDateStamps -XX:-OmitStackTraceInFastThrow -Datlassian.cluster.scale=true -DjvmRoute=node2"

Install Apache and configure it as a reverse proxy load balancer

Install apache along with its reverse load-balancer options. Become root, then:

apt-get install apache2
apt install -y libapache2-mod-proxy-html libxml2-dev

Then enable the correct modules. Run a2enmod, and provide it with the list of modules.

a2enmod
proxy proxy_ajp proxy_http rewrite deflate headers proxy_balancer proxy_connect proxy_html lbmethod_byrequests slotmem_shm

Now edit the apache conf file to configure it.

vi /etc/apache2/sites-available/000-default.conf

The result should look like this - note that the ports and routes should match with the node settings:

ProxyRequests off




ServerName MyCompanyServer





# JIRA node 1
BalancerMember route=node1
# JIRA node 2
BalancerMember 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





# Here's how to enable the load balancer's management UI if desired

SetHandler balancer-manager




# You SHOULD CHANGE THIS to only allow trusted ips to use the manager
Order deny,allow
Allow from all





# 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

Restart apache:

service apache2 restart

Change the context path for both JIRA nodes, i.e. change the base URL, so both nodes are going through the balancer:

vi /opt/atlassian/jira/conf/server.xml
vi /opt/atlassian/jira1/conf/server.xml

The Context path should look like this: Start up the nodes.

/etc/init.d/jira start
/etc/init.d/jira1 start

With any luck, your cluster should now be up and working at this url:

http:localhost/jiracluster/

You may be prompted to obtain a cluster license. Just follow the onscreen instructions to obtain a temporary license.

We hope this has helped - happy testing!