Before you Start
- 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.
- Note that you need current software maintenance to perform the upgrade.
- Confirm that your license support period is still valid before you try to upgrade.
- 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.
- 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.)
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
Before you begin the Confluence upgrade, you must back up the following:
- 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/classesdirectory in your Confluence Installation directory. 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.
- 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.
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.
- Back up your Confluence Installation directory or your Confluence webapp (if you are using Confluence EAR-WAR edition). 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.
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.