Upgrading Confluence Data Center

This page contains instructions for upgrading an existing Confluence cluster.

If you are not yet running a clustered instance of Confluence, see Moving to Confluence Data Center.

In this guide we'll use the following terminology:

  • installation directory - this is the directory where you installed Confluence on each 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 - this is a directory that is accessible to all nodes in the cluster via the same path. If you're upgrading from Confluence 5.4 or earlier you'll create this directory as part of the upgrade.  
  • Synchrony directory - this is the directory where you downloaded Synchrony (this can be on a confluence node, or on its own node)

Currently using Confluence Server? Learn more about the benefits of Confluence Data Center.

On this page:

1. Back up

We strongly recommend that you backup your Confluence home and install directories and your database before proceeding.

More information on specific files and directories to backup can be found in Upgrading Confluence.

2. Stop the cluster

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

We recommend configuring your load balancer to redirect traffic away from Confluence until the upgrade is complete on all nodes.

3. Upgrade the first node

To upgrade the first node:

  1. Extract (unzip) the files to a directory (this will be your new installation directory, and must be different to your existing installation directory)
  2. Update the following line in the <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.properties file to point to the existing local home directory on that node.
  3. Copy the jdbc driver jar file from your existing Confluence installation directory to  confluence/WEB-INF/lib in your new installation directory. 
    The jdbc driver will be located in either the <Install-Directory>/common/lib or <Installation-Directory>/confluence/WEB-INF/lib directories. 
  4. Copy any other immediately required customizations from the old version to the new one (for example if you are not running Confluence on the default ports or if you manage users externally, you'll need to update / copy the relevant files - find out more in Upgrading Confluence Manually)
  5. Start Confluence, and and confirm that you can log in and view pages before continuing to the next step. Don't try to edit pages at this point. 

You should now reapply any additional customizations from the old version to the new version, before upgrading the remaining nodes.

4. Set up or upgrade Synchrony

The first time you upgrade from Confluence 5.x to Confluence 6.x you will need to set up your Synchrony nodes, as follows. 

Set up your Synchrony cluster...


In this example, we assume you'll run Synchrony in its own cluster.
  1. Grab the <install-directory>/bin/synchrony directory from your first Confluence node and move it to your Synchrony node.  We'll call this your <synchrony-home> directory.
  2. Copy synchrony-standalone.jar from your Confluence local home directory to your <synchrony-home> directory. 
  3. Copy your database driver from your Confluence <install-directory>/confluence/web-inf/lib to your <synchrony-home> directory or other appropriate location on your Synchrony node.
  4. Edit the <synchrony-home>/start-synchrony.sh or start-synchrony.bat file and enter details for the parameters listed under Configure parameters.
    See Configuring Synchrony for Data Center for more information on the required parameters and some and optional properties that you can also choose to specify.
  5. Start Confluence then head to 
    to check that Synchrony is available
  6. Copy your <synchrony-home> directory to each Synchrony node. As each node joins you'll see something like this in your console.

    Members [2] {
    	Member []:5701
    	Member []:5701 
  7. Configure your load balancer for Synchrony.
    Your load balancer must support WebSockets (for example NGINX 1.3 or later, Apache httpd 2.4, IIS 8.0 or later). SSL connections must be terminated at your load balancer so that Synchrony can accept XHR requests from the web browser. 

If you're already running Confluence 6.x, you should upgrade your Synchrony nodes:

  1. Grab the new synchrony-standalone.jar from the <local-home> directory on your upgraded Confluence node.
  2. Copy the new synchrony-standalone.jar to each of your Synchrony nodes, and start Synchrony as normal. 

5. Start Confluence on Node 1

In this example, we assume you use the same load balancer for Synchrony and Confluence, as shown in Configuring Synchrony for Data Center.

  1. Start Confluence on node 1 and pass the following system property to Confluence to tell Confluence where to find your Synchrony cluster.

    -Dsynchrony.service.url=http://<synchrony load balancer url>/synchrony/v1

    For example http://yoursite.example.com/synchrony/v1. You must include /v1 on the end of the URL.

    If Synchrony is set up as one node without a load balancer, use the following instead:

    -Dsynchrony.service.url=http://<synchrony ip or hostname>:<synchrony port>/synchrony/v1

    For example or http://synchrony.example.com:8091/synchrony/v1

    You may want to add this system property to your <install-directory>/bin/setenv.sh or setenv.bat so it is automatically passed every time you start Confluence. See Configuring System Properties for more information on how to do this in your environment.

  2. Head to  > General Configuration > Collaborative editing to check that this Confluence node can connect to Synchrony. 

    Note: to test creating content you'll need to access Confluence via your load balancer.  You can't create or edit pages when accessing a node directly.

6. Copy Confluence to remaining nodes

The next step is to replicate your upgraded Confluence directories to other nodes in the cluster.  

  1. Stop Confluence on the first node.
  2. Copy the installation directory and local home directory from the first node to the next node. 
    If the path to the local home directory is different on this node, edit the confluence-init.properties to point to the correct location. 
  3. Start Confluence, and and confirm that you can log in and view pages on this node.
  4. Stop Confluence on this node before continuing with the next node. 

Repeat this process for each remaining node. 

7. Start Confluence and check cluster connectivity 

Once all nodes have been upgraded you can start Confluence Data Center on each node, one at a time (starting up multiple nodes simultaneously can lead to serious failures).

The Cluster monitoring console ( > General Configuration > Clustering) includes information about the active cluster nodes. When the cluster is running properly, you should be able to see the details of each node. 

Last modified on Oct 15, 2018

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.