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

6 votes
Answer 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
Community showcase
Published Mar 12, 2019 in Confluence

Confluence Admin Certification now $150 for Community Members

More and more people are building their careers with Atlassian, and we want you to be at the front of this wave! Important Dates Start the Certification Prep Course by 2 April 2019 Take your e...

710 views 2 13
Read article

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