This guide covers installing Confluence Data Center, which is a clustered solution, for the first time (with no existing data).

If you have an existing Confluence instance, see Moving to Confluence Data Center.

1. Clustering requirements and terminology

To run Confluence in a cluster you must:

  • have a clustered license.
  • use a supported external database, operating system and Java version.
  • use a load balancer with session affinity in front of the cluster.
  • have a shared directory accessible to all cluster nodes in the same path (this will be your shared home directory)
  • use OAuth authentication if you have application links to other Atlassian products (such as JIRA).

If you need a Data Center evaluation license please contact us.

In this guide we’ll use the following terminology:

  • installation directory – this is the directory where you installed Confluence on a node.
  • local home directory – this is the home or data directory on each node (in non-clustered Confluence this is simply known as the home directory).
  • shared home directory – is the directory you created that is accessible to all nodes in the cluster via the same path.

At the end of the installation process you will have an installation and local home directory on each node, and a single shared home directory (5 directories total in a two node cluster).

2. Install Confluence on the first node

  1. Install Confluence on node 1.
    See Installing Confluence on Windows from Zip File or Installing Confluence on Linux from Archive File for more information.
  2. Start Confluence on Node 1. The setup wizard will guide you through setting up the first node.  You’ll be prompted to enter:
    • your cluster license
    • a name for your cluster
    • the path to the shared home directory you created earlier.
    • a multicast address (this is automatically generated, or you can choose to enter your own)
    • the network interface Confluence will use to communicate between nodes.

3. Load test the single node

Most Confluence installations do not need to be clustered. You might want to test your single node installation with the number of users and load you expect before going ahead with the additional complexity of clustering.

4. Copy Confluence to second node

To copy Confluence 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 installation directory from node 1 to node 2.
  4. Copy the local home directory from node 1 to node 2.
    If the file path of the local home directory is not the same on nodes 1 and 2 you’ll need to update the /confluence/WEB-INF/classes/confluence-init.properties file on node 2 to point to the correct location.

Copying the local home directory ensures the Confluence search index, the database and cluster configuration, and any other settings are copied to node 2.

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

It’s best 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 monitoring console ( > General Configuration > Clustering) includes information about the active cluster.

When the cluster is running properly, this page displays the details of each node, including system usage and uptime. Use the menu to see more information about each node in the cluster.

Screenshot: Cluster monitoring console


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. Search for the new document on node 1, ensure it appears.
  4. Search for the new document on node 2, ensure it appears.

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

Install and configure your load balancer.  You can use the load balancer of your choice, but it needs to support ‘cookie based session affinity’.

You can verify that your load balancer is sending requests correctly to your existing Confluence server by simply accessing Confluence through the load balancer and creating a page then checking that this page can be viewed/edited by another machine through the load balancer.

Troubleshooting

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

If you are testing Confluence Data Center by running the cluster on a single machine, please refer to our developer instructions on Starting a Confluence cluster on a single machine.

Upgrading a cluster

It is important that upgrades follow the procedure for Upgrading Confluence Data Center.

This guide covers the process of migrating from Confluence Server to Confluence Data Center, which is a clustered solution.

If you are installing Confluence for the first time (you do not have any existing Confluence data to migrate), see Installing Confluence Data Center.

Moving from Server to Data Center

Clustering requirements and terminology

To run Confluence in a cluster you must:

  • have a clustered license
  • use an external database
  • use a load balancer with session affinity in front of the cluster
  • have a shared directory that is accessible by the same path to all cluster nodes (this will be your shared home directory)
  • use OAth authentication if you have application links to other Atlassian products (such as JIRA).

If you need a Confluence Data Center evaluation license please contact us.

In this guide we’ll use the following terminology:
  • installation directory – this is the directory where Confluence is installed.
  • local home directory – this is the home or data directory on each node (in non-clustered Confluence this is simply known as the home directory).
  • shared home directory – is is the directory you created that is accessible to all nodes in the cluster via the same path.

At the end of the installation process you will have an installation directory and local home directory on each node and a single shared home directory (for example in a two node cluster you would have a total of 5 directories).

1. Upgrade Confluence Server 

You cannot upgrade your version of Confluence and switch Confluence Data Center at the same time.  For example if you have Confluence 5.4 you’ll need to upgrade to Confluence Server 5.6 before you migrate to Confluence Data Center 5.6.

If you are upgrading from an older version of Confluence as part of your migration to Confluence Data Center you will need to follow the normal procedure for backing up and upgrading Confluence to the same version first. See upgrading Confluence for information on upgrading and choosing the best upgrade path.

Once you have ensured the upgrade was successful and your instance is working correctly, shut down Confluence.

2. Create a shared home directory 

  1. Create a directory that is accessible to all cluster nodes via the same path. This will be your shared home directory.
  2. In your existing Confluence home directory move contents of /shared-home to the new shared home directory you just created.
    To prevent confusion, we recommend deleting the empty /shared-home directory once you’ve moved its contents.
  3. Move your attachments directory to the new shared home directory (skip this step if you currently store attachments in the database).

3. Upgrade to Data Center 

  1. Download the Clustered edition of Confluence (for the version you just upgraded to).
  2. Upgrade to the Data Center version of Confluence.
    Note: your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties) should still be pointing to your existing (local) home directory.
  3. Start Confluence Data Center (run start-confluence.sh or start-confluence.bat)
  4. The setup wizard will guide you through setting up the first node.  You’ll be prompted to enter:
    • your cluster license
    • a name for your cluster
    • the path to the shared home directory you created earlier.
    • a multicast address (this is automatically generated, or you can choose to enter your own).
    • the network interface Confluence will use to communicate between nodes.

Your first node is now up and running.  

4. Copy Confluence to second node

To copy Confluence 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 installation directory from node 1 to node 2.
  4. Copy the local home directory from node 1 to node 2.
    If the file path of the local home directory is not the same on nodes 1 and 2 you’ll need to update the /confluence/WEB-INF/classes/confluence-init.properties file on node 2 to point to the correct location.

Copying the local home directory ensures the Confluence search index, the database and cluster configuration, and any other settings are copied to node 2.

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

It’s best 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 monitoring console ( > General Configuration > Clustering) includes information about the active cluster.

When the cluster is running properly, this page displays the details of each node, including system usage and uptime. Use the menu to see more information about each node in the cluster.

Screenshot: Cluster monitoring console


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. Search for the new document on node 1, ensure it appears.
  4. Search for the new document on node 2, ensure it appears.

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

Install and configure your load balancer.  You can use the load balancer of your choice, but it needs to support ‘cookie based session affinity’.

You can verify that your load balancer is sending requests correctly to your existing Confluence server by simply accessing Confluence through the load balancer and creating a page then checking that this page can be viewed/edited by another machine through the load balancer.

Troubleshooting

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

If you are testing Confluence Data Center by running the cluster on a single machine, please refer to our developer instructions on Starting a Confluence cluster on a single machine.

Moving from Data Center to Server

These instructions cover how to move from Data Center (clustered) to Server (non-clustered). In these instructions we’ll assume that you will use one of your existing cluster nodes as your new non-clustered installation.

You’ll need a Confluence Server license to switch back to Server.

1. Stop the cluster

You must stop all the nodes in the cluster before proceeding.

We recommend configuring your load balancer to redirect traffic away from Confluence.

2. Move items in the cluster shared home back to local home

  1. Create a directory called /shared-home in the  directory on one node (if you removed this directory when installing Data Center).
  2. Move the entire config directory from your  directory to the <local home>/shared-home directory.
  3. Move the remaining contents of your  directory to the root of your  directory.

Your cluster’s shared home directory should now be empty.

3. Upgrade to Confluence server

  1. Download the Server (non-clustered) edition of Confluence (you must use the same version as is currently installed).
  2. Upgrade to the Server version of Confluence.
    Note: your home directory (configured in confluence\WEB-INF\classes\confluence-init.properties) should point to your local home directory.
  3. Start Confluence Server (run  start-confluence.sh or start-confluence.bat)
  4. The setup wizard will guide you through applying your Confluence Server license and complete the migration process.

To confirm you are now running the non-clustered edition, go to  > General Configuration. The Cluster Configuration page should not appear.

Posted by:.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s