What is the best practice to Upgrade Confluence?

[GuilhermeA]

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?

[Matt · Accepted solution]

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.

[Tiago Comasseto]

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.