Scarlet
 
PDF -icon
PDF

Scarlet - Jira Clustering How-To

This is a step-by-step installation and configuration guide for setting up your Jira cluster with the Scarlet extension.

Preliminary Words

The following steps will guide you through the process of setting up your cluster comprised of one or more Jira application nodes acting as clients of one, single, Terracotta server node.
Please note that we will assume that every node will have its own computer box.
For any other information regarding the physical cluster architecture take a look here.

Important
This document always refers to the latest Scarlet version.

Prerequisites

Steps

Step 1

Prepare every cluster node by creating the same directory structure for every Jira installation. In particular:

  • Set up a shared filesystem or storage area network providing a shared location for attachments. Then mount the networked filesystem on every cluster node under the same location (say /var/jira/attachments).
  • Set up a shared filesystem or storage area network providing a shared location for backups. Then mount the networked filesystem on every cluster node under the same location (say /var/jira/backups).

Moreover, set up a Jira-supported database by creating proper users and permissions according to http://www.atlassian.com/software/jira/docs/latest/databases/index.html : this database instance will be shared among all nodes.

Important
You need a shared filesystem only for attachments and backups.

Step 2

Install Jira on the local filesystem of every cluster node by simply extracting the downloaded archive, and configure the Jira-related database files as described at http://www.atlassian.com/software/jira/docs/latest/databases/index.html.
Let's call $JIRA_DIR the directory where you extracted your Jira distribution.

Important
For Microsoft Windows users: do not install the application server which will host your Jira instances as an automatic service, because it's strongly suggested to manually startup/shutdown it.
Important
Be careful not to start any Jira instance at this point.

Step 3

Install Terracotta on the local filesystem of all Jira nodes and of the dedicated server node by simply extracting the Terracotta distribution archive. Even if not strictly required, it's definitely convenient to install Terracotta under the same location on every node, including the server one.
Let's call now $TC_DIR the directory where you extracted your Terracotta distribution (provided that you used the same location for all clients and server nodes as suggested above).

Step 4

Copy the Scarlet extension archive on the local filesystem of all Jira nodes and of the Terracotta server node, then unpack its contents anywhere you want.
Let's call now $SCARLET_DIR the directory where you extracted your Scarlet distribution.

Step 5

Configure all Jira nodes by doing the following on each node:

  • Change directory to $SCARLET_DIR.
  • Configure the following properties into the local.build.properties file:
    • jira.install.dir : your $JIRA_DIR (the directory where you locally installed Jira).
    • terracotta.install.dir : your $TC_DIR (the directory where you locally installed the Terracotta distribution).
    • terracotta.server.conf.dir : a directory where you want your Terracotta-related files to be stored (e.g. /etc/scarlet).
    • terracotta.server.ip : the IP address of the Terracotta server node.
    • terracotta.server.port : the port of the Terracotta server node; you can leave the default value here (9510).
    • terracotta.runtime.logging : set it true to enable a more detailed logging, or false (default) to disable it.
    Important
    On Windows environments, you must use double backslashes for file system locations.
  • Now, depending on your Jira distribution:
    • Standalone distribution:
      • Stay on $SCARLET_DIR.
      • Run the following command: ant configure-standalone-node
    • WAR distribution:
      • Stay on $SCARLET_DIR.
      • Run the following command: ant configure-war
      • Complete the configuration and installation process as described here.
      • Modify your application server startup script in order to call either the tc-config.sh or tc-config.bat script before actually starting up the server process.
        Note
        You can find these scripts under your $JIRA_DIR/bin directory.
Warning

If you have to configure some Java options through the JAVA_OPTS environment variable, be careful not to overwrite already existent values, because this could remove Scarlet-related configuration options. You can keep existent values by doing the following:

export JAVA_OPTS="$JAVA_OPTS ..."

set JAVA_OPTS=%JAVA_OPTS% ...

Important
Be careful not to start any Jira instance at this point.

Step 6

Configure the Terracotta server by doing the following on the server node only:

  • Change directory to $SCARLET_DIR.
  • Configure the following properties into the local.build.properties file:
    • terracotta.install.dir : your $TC_DIR (the directory where you locally installed the Terracotta distribution).
    • terracotta.server.conf.dir : a directory where you want your Terracotta-related files to be stored (e.g. /etc/scarlet).
      Note
      This directory will also store the server logs and the cluster shared data: make sure to have enough disk space!
    • terracotta.server.ip : the IP address of your Terracotta server node.
    • terracotta.server.port : the port of your Terracotta server node; you can leave the default value here (9510).
    Important
    On Windows environments, you must use double backslashes for file system locations.
  • Run the following command: ant configure-tc-server.

Step 7

Run the Terracotta server with one of the following commands:

  • $TC_DIR/bin/start-tc-server.sh \-f terracotta.server.conf.dir/tc-config.xml
  • $TC_DIR\bin\start-tc-server.bat \-f terracotta.server.conf.dir\tc-config.xml

Step 8

Run just one Jira node (whichever you want) by doing the following (depending on your Jira distribution):

  • Standalone distribution:
    • Run one of the following commands, depending on your operating system:
      • $JIRA_DIR/bin/tc-startup.sh
      • $JIRA_DIR\bin\tc-startup.bat
      • Important
      Startup scripts must be run by the $JIRA_DIR directory.
  • WAR distribution:
    • Run your application server startup script.

Then point your browser to the URL of your running Jira (say http://localhost:8080) and follow the usual Jira configuration wizard.

Important
The Jira configuration wizard must be executed by only one node, while all other cluster nodes are shut down. Once completed you will be able to startup all cluster nodes.

Step 9

Run all other Jira nodes as described in the previous step: all nodes will automatically join the cluster.

Step 10

Configure your HTTP load balancer for the Jira cluster, enabling sticky sessions ... and enjoy your clustered Jira!