Upgrading Confluence EAR-WAR Distribution

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:

Upgrading to Confluence 5.6?

If so, please review the Confluence 5.6 Release Notes for important information about this version of Confluence.

Also, we strongly recommend that you check the upgrade notes for every major version of Confluence that you are skipping, since there might be specific changes between Confluence versions that could affect your Confluence installation. The upgrade notes for recent major versions of Confluence are accessible from the Upgrade Notes Overview page.

Finally, please check the Supported Platforms page to ensure that your Java version, operating system, application server, database and browser are supported for this release of Confluence. The End of Support Announcements for Confluence page has important information regarding supported platforms.

On this page:

Before you Start

  1. If you are planning to change to a different database, we recommend that you complete the Confluence upgrade first. Then follow the instructions on migrating to a different database.
  2. Note that you need current software maintenance to perform the upgrade.
  3. Confirm that your license support period is still valid before you try to upgrade.
  4. If your current license has expired but you have a new license with you, please update your license in Confluence before performing the upgrade.
    (warning) If you forget to do this and your license has expired, you will receive errors during the upgrade process. Refer to the instructions on upgrading beyond current license period.
  5. Check the release notes for the new version of Confluence you are installing, plus the upgrade notes for any major versions you are skipping. It is important to read these upgrade notes as there might be specific changes between Confluence versions that could affect your Confluence instance. The upgrade notes pages for recent major versions of Confluence are accessible from the Upgrade Notes Overview page. (Each upgrade notes page is a 'child' of its respective release notes page.)
  6. Make sure that your environment (e.g. the database system, the operating system, the application server and so on) still complies with the Confluence System Requirements. A newer version of Confluence may have different requirements than the previous version.
  7. If you are using Confluence EAR-WAR edition, check Installing the Confluence EAR-WAR Edition to see if there is anything extra you will need to do to get Confluence running.
  8. If you are using an external database, familiarise yourself with all known issues for your specific database. Also make sure the Confluence database connector principal (the database user account) has sufficient permissions to modify the database schema.
  9. Note which plugins (add-ons) are installed and enabled on your current Confluence site. Please verify whether a compatible version of the plugin is available in the version of Confluence you are upgrading to. This information is available via the Confluence Upgrade Check in the plugin administration section of Confluence. See the documentation: Checking add-on compatibility with application updates. You can also check the respective home pages for these plugins on the Atlassian Plugin Exchange. Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading Confluence.  Please test these first by applying them to the latest Confluence version in a test environment.
  10. If you have made any customisations to Confluence, please verify their compatibility in the latest version. For example, if you have modified any layouts or are using your own custom theme, please test these first by applying them to the latest Confluence version in a test environment. You can see the customisations applied to your Confluence installation.
  11. Some anti-virus or other Internet security tools may interfere with the Confluence upgrade process and prevent the process from completing successfully. If you experience or anticipate experiencing such an issue with your anti-virus/Internet security tool, disable this tool first before proceeding with the Confluence upgrade.
  12. After upgrading, Confluence may need to rebuild its indexes. If this happens, there may be some extra load placed on the server following the upgrade. Make sure to schedule any upgrade of production Confluence outside of hours where people need to use it.

Backing Up

Before you begin the Confluence upgrade, you must back up the following:

  1. Back up your Confluence Home directory. The location of the Home directory is stored in a configuration file called confluence-init.properties, which is located inside the confluence/WEB-INF/classes directory in your Confluence Installation directory. (info) The Confluence installer will automatically prompt you to run a backup, storing the files in a .zip archive at the same level as your Confluence Home directory.
  2. Back up your database. Perform a manual backup of your external database before proceeding with the upgrade, and double check that the backup was actually created properly. If you are not a database expert, or unfamiliar with the backup-restore facilities of your database, simply restore the backup to a different system to ensure the backup worked before proceeding. This recommendation is generally a good best practice. Surprisingly, many companies get in trouble for broken database backups because they skip this basic but vital "smoke test" of the operation.
    (info) The 'embedded database' is the HSQLDB database supplied with Confluence for evaluation purposes. You don't need to back it up since it is stored in the Confluence home directory. You should not be using this database for production systems at all, so if you happen to be using HSQLDB in a production system, please migrate to a proper database before the upgrade. Read about the various shortcomings of HSQLDB.
  3. Back up your Confluence Installation directory or your Confluence webapp (if you are using Confluence EAR-WAR edition). (info) The Confluence installer will automatically back up these files, storing the files in a .zip archive at the same level as your Confluence installation directory.

Testing the Upgrade in a Test Environment

Be sure to test the upgrade in a test environment before proceeding on your production server.

 

     1. Create a snapshot of your current production Confluence environment on a test server, as described in the page on Moving Confluence Between Servers.

XML imports

(warning) Importing an old XML backup file to a new major version (for example, Confluence 3.5 to Confluence 4.0) is not recommended. Please recreate your production instance in a test environment first.

      2. Perform the upgrade on your cloned environment.

      3. Test all your unsupported plugins (add-ons) and any customisations with the new version before proceeding on your production server. You can read more about supported and unsupported plugins.

Performing the Upgrade

If you are migrating servers or migrating databases, perform those operations in separate steps.

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).

      Upgrading to Confluence 3.5+ and using JIRA user management?

      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.
    (info) 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

Hint: The steps below are for advanced Confluence users, who have applied special settings to their Confluence server and/or Confluence look and feel

 

After upgrading your Confluence installation to a later version of Confluence, you need to consider any customisations you have applied to your system and other special configurations:

  • If you had previously installed Confluence/Tomcat as a Windows service, uninstall the service (to ensure that the old Confluence cannot start automatically when the server restarts) and reinstall the new one. For details please see Start Confluence Automatically on Windows as a Service.
  • If you are using the Confluence distribution and you have previously defined a CATALINA_HOME environment variable, please check that it points to the correct path for the new Confluence Tomcat server.
  • If you had previously connected your Confluence installation to an external database via a JNDI datasource or you implemented SSL, edit your new web.xml file and and copy over any relevant modifications from your old web.xml file, which relate to these customisations.
  • If you were previously running Confluence on a non-standard port, edit your new <Installation-Directory>\conf\server.xml file as described in Change listen port for Confluence.
  • If you had previously defined a Tomcat datasource, edit your new <Installation-Directory>\conf\server.xml and copy over the datasource definition from your old server.xml.
  • If you were previously using any plugins, install the latest compatible version and disable any plugins that are incompatible with your new version of Confluence. The easiest way to do this is to use the Universal Plugin Manager in the Confluence Administration Console.
  • If you are using any customised themes, please check that they are displaying as expected. Some further customisation may be required to ensure compatibility with your new version of Confluence.
  • If you had previously customised the default site or space layouts, you will need to reapply your changes to the new defaults as described here.
  • If you had previously modified the Confluence source code, you will need to reapply your changes to the new version.
  • If you were previously running Confluence over SSL, you will need to reapply your configuration as described in Running Confluence Over SSL or HTTPS.
  • If you had previously modified the memory flags (Xms and Xmx) in either the <Installation-Directory>\bin\setenv.sh or the <Installation-Directory>\bin\setenv.bat file, you may want to make the modifications in your new installation. The parameters are specified in the CATALINA_OPTS variable.
  • If you had changed the Confluence interface text, you will need to pull over the ConfluenceActionSupport.properties file.
  • If you were using a custom SSO authenticator, change seraph-config.xml to the correct authenticator.

Checking for Known Issues and Troubleshooting the Confluence Upgrade

After you have completed the steps required to upgrade your Confluence installation, check all the items on the Confluence post-upgrade checklist to ensure that everything works as expected. If something is not working correctly, please check for known Confluence issues and try troubleshooting your upgrade as described below:

  • Check for known issues. Sometimes we find out about a problem with the latest version of Confluence after we have released the software. In such cases we publish information about the known issues in the Confluence Knowledge Base. Please check the known issues for the relevant release on this page of the Knowledge Base and follow the instructions to solve the problem.
  • Check for answers from the community. Other users may have encountered the same issue. You can check for answers from the community at Atlassian Answers.
  • Did you encounter a problem during the Confluence upgrade? Please refer to the guide to troubleshooting upgrades in the Confluence Knowledge Base.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport