Before you Start

1. Note that you need current software maintenance to perform the upgrade.
2. Confirm that your license support period is still valid before you try to upgrade.
3. If your current license has expired but you have a new license with you, please update your license in Confluence before performing the upgrade.
   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.
4. 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.)
   If you are upgrading from a version of Confluence prior to 2.5.5, the upgrade notes information is located under a heading on the release notes pages.
5. 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.
6. If you are using Confluence EAR-WAR edition, check Installing the Confluence EAR-WAR Edition for your specific application server, to see if there is anything extra you will need to do to get Confluence running. For example:
   • Resin 3 users will need to update web.xml.
7. 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 login) has sufficient permissions to modify the database schema.
8. Note which plugins are installed/enabled on your current Confluence instance. Please verify whether a compatible version of the plugin is available in the version of Confluence you are upgrading to. This information is available on 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. This can be done via the 'Plugin Repository' in your Administration Console. Please test these first by applying them to the latest Confluence version in a test environment.
9. 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.

Backing Up

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

1. Back up your Confluence Home directory. The Confluence Home directory is the folder where Confluence stores its configuration information, search indexes and page attachments. If you're using the embedded HSQLDB database supplied for evaluation purposes, the database files are also stored in this directory.
   Tip: Another term for 'Home directory' would be 'data 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.
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, you should try to restore the backup to a different system to ensure the backup worked, before proceeding. This recommendation is not specific to Confluence usage but just common sense: Surprisingly many companies, even banks, get in trouble for broken database backups.
   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 home directory. But you should not use this database for production systems anyway, so if you happen to accidentally still use HSQLDB in a production system, please migrate to a proper database before the upgrade.
3. Back up your Confluence Installation directory (if you are using Confluence Standalone) or your Confluence webapp (if you are using Confluence EAR-WAR edition). The 'Confluence Installation directory' is the directory into which the Confluence application files and libraries have been unpacked (unzipped) when Confluence was installed. Confluence does not modify or store any data in this directory. This directory is also sometimes called the 'Confluence Install directory'.

Testing the Upgrade in a Test Environment

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

Import an old xml backup file to a new version is not recommended. Please recreate your production instance in a Test Environment first.

1. Perform the upgrade on your cloned environment.
2. Test all your unsupported plugins and any customisations with the new version before proceeding on your production server. You can read more about supported and unsupported plugins​.

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 a Standalone Edition of Confluence 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 Standalone.
• 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 Plugin Repository 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 Adding SSL for Secure Logins and Page Security.
• 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 JAVA_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 or the utility to Automatically Add LDAP users to the confluence-users Group, change seraph-config.xml to the correct authenticator.

After you have completed the steps above 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 Confluence 3.3 Known Issues on the front page of the Knowledge Base and follow the instructions to apply any necessary patches.
  
  
• Did you encounter a problem during the Confluence upgrade? Please refer to the guide to troubleshooting upgrades in the Confluence Knowledge Base.