Upgrading a Confluence Cluster

This page contains instructions for upgrading an existing Confluence cluster to a new version of Confluence. If you are not running a clustered instance of Confluence and wish to, see Confluence Cluster Installation with Existing Data.

Oracle Coherence Licensing Change:

Due to a license agreement change,Confluence is now available in two editions:
- Standard Edition — Confluence with Ehcache's caching technology (available to customers with non-clustered Confluence licenses).
  If you are currently running a clustered installation of Confluence, please do not upgrade it with a standard edition of Confluence.
- Clustered Edition — Confluence with Oracle's Coherence clustering and distributed caching technology (available to customers with Confluence clustered licenses only).
For more information about these changes, please refer to the Coherence License Changes document.
If you have a Confluence clustered license, are running a clustered installation of Confluence and wish to upgrade to Confluence version 2.6 or later, please ensure that you download only a clustered edition of Confluence and please refer to the Confluence 3.0.1 Upgrade Notes for additional upgrade information.

You can download the latest version of Confluence from here.

Overview

The steps involved in upgrading a multi-node Confluence cluster are:

Backup your confluence instance.
Read the Release Notes for this version and check you have the required expertise to perform the upgrade.
Stop each node in the cluster.
Install the new version into the application server on the first node.
Install the new version into the application server onto the remaining nodes.

Step One: Backing up

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

For specific files to backup see Upgrading Confluence.

Step Two: Things you need to check ...

Always check the release-notes for the version of Confluence you are installing for upgrade instructions specific to that version.
To perform this upgrade you must be familiar with the usage of the application server running your Confluence Cluster, and the web server load balancing it.
Check the Configuring Confluence for your application server and database, to make sure there isn't anything extra you need to do to get Confluence running.
Check that you know what configurations or customisations have been made to your Confluence instance. These may include specialised user management configurations and changes to Confluence's Java classes and Velocity templates.

Step Three: Stopping the cluster

It is vital that all nodes in the cluster are running the same version of Confluence. That's why the first step is to stop all the nodes.

Stop the Confluence application on each node using your application server.

Step Four: Upgrading the first node

We advise configuring your load balancing web server to redirect traffic away from Confluence until the upgrade is complete on multiple nodes.

Upgrading a cluster node uses the same process as Upgrading Confluence.

Unzip the new version.
Edit its confluence-init.properties to point to the existing home directory.
Port any immediately required customisations from the old version to the new one. Eg atlassian-user.xml.
Install the new version into the application server. Eg for Tomcat edit confluence.xml or server.xml to point to the new location, and restart Tomcat.
Wait for the Node to finish upgrading and confirm that you can log in and view pages before continuing to Step Five.
Port any additional customisations from the old version to the new version. Eg modifications to Java classes or Velocity templates.

Step Five: Upgrading other nodes

Copy the confluence installation, complete with customisations, to the next node.

Edit its confluence-init.properties to point to the existing home directory.
Install the new version into the application server. Eg for Tomcat 5 edit confluence.xml to point to the new location, and restart Tomcat.
Wait for the Node to finish upgrading and confirm that you can log in and view pages before continuing with the next node.

Troubleshooting

For suggested troubleshooting techniques, see our Cluster Troubleshooting page.

Page tree