This document tells you how to upgrade from one version of Confluence to a later version. These instructions apply to the EAR-WAR Distribution of Confluence, deployed on your own existing application server.

If you want to upgrade the regular Confluence distribution, which includes Apache Tomcat as the application server, please refer to Upgrading Confluence instead.

Please also check the following before you start using this guide:

• The version of Confluence that you will be upgrading to. Refer to the documentation home page to verify the latest Confluence version and to find documentation for older versions.
• The supported platforms for the version that you will be upgrading to. Please see the Supported Platforms page for the version of Confluence that you will be upgrading to, as well as the End of Support Announcements for Confluence.
• If you are running Confluence on a cluster, please see Upgrading Confluence Data Center instead of this document.

On this page:

Performing the Upgrade

The upgrade process allows you to unzip the new Confluence installation into a directory of your choice and then edit the configuration files to point your new installation to your existing data files. Follow these instructions:

1. Shut down your existing Confluence instance.
2. Download the Confluence EAR-WAR zip file: Go to the Download Center, and click 'Show all' to find the EAR-WAR zip file.
3. If you are on Windows, please check your unzip program before extracting the downloaded zip file. Some archive-extract programs cause errors when unzipping the Confluence zip file. You should use a third-party unzip program like 7Zip or Winzip. If you do not have one, please download and install one before continuing:
   • 7Zip — Recommended. If in doubt, download the '32-bit.exe' version
   • Winzip
4. Use your unzip program to unzip the installation file. You should now have a new directory called confluence-<version>.
   • In the rest of this document, we will refer to this as the <Installation-Directory>.
   • Do not use spaces in your directory path.
   • You can read more about the Confluence Installation directory.
5. Edit the confluence-init.properties file found at: <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.properties
   and update 'confluence.home' to point to your existing Confluence Home directory.
   • Make sure you have first backed up your Home directory.
   • Open the confluence-init.properties file in a text editor such as Notepad.

   • Scroll to the bottom and find this line:

     # confluence.home=c:/confluence/data

   • Remove the '#' and the space at the beginning of this line, so that Confluence no longer regards the line as a comment. The line should now begin with confluence.home.
   • Update the directory name after the = sign, to point to your existing Confluence Home directory.
6. If you are using Tomcat, you need to update either your confluence.xml or server.xml (depending on where you have defined the Confluence context descriptor) to point to the location of the new Confluence installation (also remember to copy over any customisations such as a tomcat datasource if you have one).
7. If you have delegated your user management to JIRA, LDAP 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).

     Please review our KB article first: Upgrade to Confluence 3.5 with JIRA User Management Fails

     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" />

8. 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. If you need more information, please refer to the Crowd documentation.
9. Restart your application server and start Confluence.
   Please note that Confluence will need to re-index attachments and this can take 5-10 minutes. Please wait until Confluence has finished indexing the attachments before trying to access Confluence via your web browser. (There is no easy and quick way to determine if the indexing process is completed. Please wait for approximately 10 minutes after the server start up before accessing Confluence via a web browser.)
10. During the startup process Confluence will create any missing database indexes. If you created any database indexes on your own, please check those afterwards and remove those that duplicate the indexes added by Confluence. Just in case you run into any errors which prevent Confluence from starting up, you can set the system property hibernate.hbm2ddl.skip_creating_missing_indexes to true to skip automatic index creation.
11. Visit Confluence in your web browser and log in using a username from your previous Confluence installation. You should be able to log in immediately, without seeing the Setup Wizard.
12. Take a quick look around your Confluence site to confirm that all your spaces and pages are present and everything looks normal. You should see the new Confluence version number in the page footer.
13. Consider any adjustments you need to make to customisations and special configurations, as described below.

Reapplying Customisations to your New Confluence

Checking for Known Issues and Troubleshooting the Confluence Upgrade