This documentation relates to the latest version of Confluence.
If you are using an earlier version, please go to the documentation home page and select the relevant previous version.

Confluence Cluster Installation

Added by Matt Ryall, last edited by Sarah Maddox on Feb 10, 2008  (view change) show comment
Confluence 2.8 Documentation

Index

Overview

There are two methods of installing Confluence in a cluster, depending on whether you have existing data. This page describes a fresh installation with no existing data.

See also Confluence Cluster Installation with Existing Data.

Installation with no existing data

To get Confluence running in a two-node cluster, you must do the following:

  1. Ensure you meet the clustering requirements, including obtaining a clustered license key from Atlassian for each node
  2. Install Confluence on a single node, configuring an external database and a cluster name
  3. Load test the single node installation, see whether clustering is required
  4. Shut down the first node, copy the Confluence application and Confluence home directory to the second node
  5. Start the first node, wait until it is running, then bring up the second node and it will automatically join the cluster
  6. Test the cluster is working correctly
  7. Configure a load balancer in front of the two clustered nodes.

Each of these steps will be described in detail below.

1. Clustering requirements

Your Confluence cluster installation must meet all the following criteria for clustering:

  • you must be running Confluence 2.3 or later
  • you must have a clustered license
  • you must use an external database
  • you must use a load balancer with session affinity in front of the cluster.

Clustered licenses are available through the Confluence website.

A cluster can run using two copies of Confluence Standalone. However, cluster administrators must understand how to configure an application server and web server with load balancing, so we recommend you are comfortable installing Confluence as a EAR/WAR in your application server before proceeding with a clustered installation.

2. Installation on first node

Cluster administrators should already be comfortable with the normal installation method, so it won't be repeated here. There are two differences in the Confluence Setup Wizard from a normal installation:

  • you must use an external database
  • you must enter a cluster name.

Cluster configuration during setup
Enter a cluster name to create a new cluster

Technical note
The cluster name will be converted into a unique multicast IP address and port for your Confluence cluster. UDP multicast traffic is used for Confluence to automatically discover other nodes in the cluster when they start up.

3. Load test the single node

Most Confluence installations do not need to be clustered. Ensure you have tested your single node installation with the number of users you expect to host before going ahead with the additional complexity of clustering.

Check out our performance tuning tips for ways to improve the performance of a single instance of Confluence.

You can upgrade your single node to a multi-node cluster at any time by resuming this guide from step 4 below.

4. Copy Confluence to second node

Confluence clusters must use the same JDK, application server and application. The easiest way to ensure this is to shut down Confluence on the first node, then copy its web application and home directory to the second node:

  1. Shut down Confluence on node #1.
  2. Shut down your application server on node #2, or stop it automatically loading web applications.
  3. Copy the Confluence web application from node #1 to node #2.
  4. Copy the Confluence home directory from node #1 to node #2.

Copying the web application ensures any modifications you have made to the application itself, custom LDAP settings (atlassian-user.xml), and any other advanced configuration are copied to node #2.

Copying the home directory ensures the Confluence search index (the index/ directory), the database and cluster configuration (confluence.cfg.xml), and any other home directory settings are copied to node #2.

5. Start Confluence on the first node, wait, then start Confluence on second node

For the most stable start-up process, it is important to start Confluence one server at a time.

  1. Start Confluence on node #1.
  2. Wait for Confluence to become available on node #1.
  3. Start Confluence on node #2.
  4. Wait for Confluence to become available on node #2.

6. Test cluster connectivity

The Cluster Administration page (Administration, Cluster Configuration) includes information about the active cluster. When the cluster is running properly, this page displays:

  • a correct count of the nodes in the cluster
  • a status display for each node in the cluster
  • an uptime for each node that is accurate.


Cluster Administration page

A simple process to ensure your cluster is working correctly is:

  1. Create a new document on node #1
  2. Ensure the new document is visible by accessing it directly on node #2
  3. Wait one minute (Confluence does batch indexing once per minute)
  4. Search for the new document on node #1, ensure it appears
  5. Search for the new document on node #2, ensure it appears.
    Technical note
    If Confluence detects more than one instance accessing the database but not in a working cluster, it will shut itself down in a cluster panic. This can be fixed by troubleshooting the network connectivity of the cluster.

7. Configure load balancer

For the moment, configuring the load balancer is outside the scope of this document.

However, a simple Apache and Tomcat load-balancing configuration is available, which includes sample configuration for the Apache Tomcat and the Apache web server, using its load-balancing JK connector.

Troubleshooting

If you have problems with the above procedure, please see our Cluster Troubleshooting guide.

Upgrading a cluster

It is important that upgrades follow the procedure for Upgrading a Confluence Cluster.

Related documentation

Overview of Confluence Clusters
Clustering in Confluence
Confluence Cluster Installation with Existing Data
Confluence Installation Guide
Upgrading a Confluence Cluster
Cluster Administration page

Labels

 

Comments (4)

 

  1. Dec 19, 2007

    Fabien Bergeret says:

    Is it possible not to use multicast but unicast ?

    Is it possible not to use multicast but unicast ?

    1. Jan 04, 2008

      Tony Cheah Tong Nyee says:

      Hi Fabien, Please find the following reply from Paul Curren

      Hi Fabien,

      Please find the following reply from Paul Curren .
      Additionally, the link below may be of help:

      Hope the information helps.

      Cheers,
      Tony

  2. Jan 30

    Anonymous says:

    We received a suggestion from Atlassian that: Session affinity for J2EE web a...

    We received a suggestion from Atlassian that:

    Session affinity for J2EE web applications means the load balancer keeps a cache which maps the JSESSIONID cookie values sent in a response to the cluster node that sent it. When a client request includes a JSESSIONID cookie that matches a value in the cache, the request should be processed by the associated server.

    Unfortunately, load balancing via the JESSIONID doesn't seem to work. We're finding that after logging in we are ending up back on the login page. Note how the JSESSION ID changed in the second attachement. You'll end up with logins that will work maybe 50% of the time you open a new browser window in a two node cluster.

    Atlassian really should provide better advice on this. The tomcat example doesn't seem to show anything about using jsessionid, it's not clear in skimming over it how it is doing the session affinity.

    1. Feb 19

      Choy Li Tham says:

      Hi, Unfortunately, load balancing via the JESSIONID doesn't seem to work. May ...

      Hi,

      Unfortunately, load balancing via the JESSIONID doesn't seem to work.

      May I know if you have encountered any problems with the load balancing via the JESSIONID? If that is the case, it would be appreciated that if you could raise a support request pertaining to the problem that you are having at the following Issue Tracker:

      Thus, we can further investigate the problem and follow up the issue from there. Thanks.

      Regards,
      Choy Li

Add Comment