What is the best practice to Upgrade Confluence?

Since the XML Backup does not work for going into different versions, e.g. 2.8 to 3.4.9, what would be the best approach?

2 answers

1 accepted

Atlassian publish 'Upgrade Notes' documentation for each release. We recommend you follow this documentation when upgrading to a specific release. Please see the Confluence 3.5 Upgrade Notes as an example.

I like to follow the steps bellow that I've created myself with the help of Morgana Spindler.

Summarizing, the upgrade steps should be the following:

1. Backup your data:

  • Create a backup or dump of your database using tools provided by your database
  • Create a file system backup of your Confluence home directory

2. Extract the zip/tar.gz file of the latest version of Confluence on the place you choose.

3. Into the extracted folder, open the file confluence-init.properties, which is located at Confluence install directory\confluence\web-inf\classes and edit the line: confluence.home=/usr/local/confluence/home to point to the path where is your new home folder of your Confluence (from backup).

4. On Confluence home folder, there is the confluence.cfg.xml file, the connections settings to your data base are saved into this file. If you have changed the name of your database server, database name, database user name or password, you need to edit this file to modify to your new parameters (from backup).

5. User management integration:

If you have delegated your user management to JIRA, LDAP, Crowd, or any other external user management system, copy the following files from your old Confluence installation to your new Confluence installation:

  • <Installation-Directory>/confluence/WEB-INF/classes/osuser.xml.
  • <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml (if you are upgrading from Confluence 2.2 or later).

If you are upgrading from an earlier version of Confluence (2.5.5 and earlier) and are copying your existing atlassian-user.xml file from your previous instance, please ensure that the hibernate cache parameter in this file has been enabled, to avoid performance related issues. (NOTE: If you use Crowd for your user management, you do not need to do this.):

  • <hibernate name="Hibernate Repository" key="hibernateRepository" description="Hibernate Repository" cache="true" />

If you have delegated your user management to Crowd, you will also need to copy the Crowd client library and configuration files from your old Confluence installation to your new Confluence installation:

  • <Installation-Directory>/confluence/WEB-INF/lib/crowd-integration-client-X.X.X.jar and <Installation-Directory>/confluence/WEB-INF/classes/crowd.properties.
  • NOTE: This steps is not needed if you are upgrading Confluence to version 3.5.x

If you need more information, please refer to the Crowd documentation.

6. Start your new Confluence instance.

Additional information:

  • Please consult this article about data base setup and JDBC drivers.
  • Into the confluence.cfg.xml file, the parameter you might need to edit are:

<property name="hibernate.connection.password">database_password</property>
<property name="hibernate.connection.url">jdbc:mysql://database_server_name/database_name?autoReconnect=true</property>
<property name="hibernate.connection.username">database_username</property>

  • More information about upgrading Confluence can be found in this article.

Suggest an answer

Log in or Sign up to answer
Atlassian Community Anniversary

Happy Anniversary, Atlassian Community!

This community is celebrating its one-year anniversary and Atlassian co-founder Mike Cannon-Brookes has all the feels.

Read more
Community showcase
Kesha Thillainayagam
Posted Apr 13, 2018 in Confluence

We want to hear how your non-technical teams are using Confluence!

Hi Community! Kesha (kay-sha) from the Confluence marketing team here! Can you share stories with us on how your non-technical (think Marketing, Sales, HR, legal, etc.) teams are using Confluen...

380 views 21 10
Join discussion

Atlassian User Groups

Connect with like-minded Atlassian users at free events near you!

Find a group

Connect with like-minded Atlassian users at free events near you!

Find my local user group

Unfortunately there are no AUG chapters near you at the moment.

Start an AUG

You're one step closer to meeting fellow Atlassian users at your local meet up. Learn more about AUGs

Groups near you