Upgrading Confluence
This document describes the procedure for upgrading to the latest version of Confluence on Windows or Linux.
Before you start
- Check your Confluence licence is valid.
To check go to
> General Configuration > Support Tools and make sure the license support period has not expired. If your support period has expired renew your licence and reapply it before proceeding with the upgrade.
- Read the Release Notes and Upgrade Notes for both the version you are upgrading to, and any versions you are skipping.
- Check that your Java version, application server, operating system, database and browsers are supported.
See Supported Platforms and End of Support Announcements for Confluence to confirm latest requirements.
- Check the latest database setup guide for your database and ensure that the database is configured correctly. There may be new configuration requirements. See Database Configuration.
- Check the compatibility of any add-ons.
Some add-ons may not yet be compatible with the latest version of Confluence. See Checking app compatibility with application updates to find out how to check this in the Universal Plugin Manager.
- Check for any known issues that might affect your instance.
See the Confluence Knowledge Base for known issues for the version you are upgrading to and Database Troubleshooting for known issues related to supported external databases.
- Make a note of any modifications to your Confluence instance (for example layouts or a custom theme).
Any customisation you wish to maintain will need to be reapplied after upgrading.
Step 1 Determine your upgrade path and method
The following table will help you to determine the most efficient upgrade path from your current version to the latest versions of Confluence. To use the table find your current installed version of Confluence in the left column and follow the suggested path.
Your Version | Recommended upgrade path to Confluence 5 |
|---|---|
| 2.7 or earlier | Upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below. |
| 2.8 to 3.4 | Upgrade to 3.5.17, and follow paths below. |
| 3.5 | Upgrade to 5.0.3 then upgrade to the latest version of Confluence 5. |
4.0 to 4.3 | Upgrade directly to the latest version of Confluence 5. |
5.0 to 5.9 | Upgrade directly to the latest version of Confluence 5. |
There are several factors that will determine the upgrade method you should use. If you:
- Are upgrading from a version earlier than Confluence 3.5 you will need to upgrade manually. You can contact Support for help determining an appropriate upgrade path.
- Are moving to a different operating system or file location you should upgrade manually.
- Currently use the EAR/WAR distribution to deploy Confluence into an existing application server, you can only upgrade manually.
- Are moving to a different database you should upgrade using the installer first and then follow the procedure outlined in migrating to a different database.
- Have a clustered instance of Confluence you should follow the procedure outlined in Upgrading Confluence Data Center.
- Are using the embedded (trial) database you should migrate to a different database before upgrading. This database is supplied for evaluation purposes only and is not recommended for production environments. See embedded HSQLDB database for more information.
otherwise you should follow the instructions below and use the Windows or Linux installer to upgrade Confluence. XML backups should not be used to upgrade Confluence.
Step 2 Upgrade Confluence in a test environment
- Create a snapshot of your current production Confluence environment on a test server - see Moving Confluence Between Servers for how to do this.
- Follow the steps below to perform the upgrade on your cloned environment.
- Test all your unsupported add-ons (plugins) and any customisation (for example custom themes and layouts) with the new version before proceeding with the upgrade in your production environment.
Step 3 Back up
- your external database
You must perform a manual backup of your external database and confirm that the backup was created properly. If you are unfamiliar with the backup-restore facilities of your database, you can simply restore the backup to a different system to ensure the backup worked before proceeding. - your Confluence Home directory
The Confluence Home directory is the folder where Confluence stores its configuration information, search indexes and page attachments. The location of the Home directory is stored in a configuration file calledconfluence-init.properties, which is located inside theconfluence/WEB-INF/classesdirectory in your Confluence Installation directory.
if you store attachments outside the Confluence Home directory, you should also backup your attachments directory. - the Confluence installation directory
This is where the Confluence application files and libraries were unpacked (unzipped) when Confluence was originally installed.
The installation wizard will back up your Confluence directories as part of the installation process, but you should also back these directions up manually before starting the upgrade.
Step 4 Upgrade Confluence in your production environment
- Download the appropriate Windows or Linux installer.
- Start the installer:
- Windows Users: run the .exe file.
If prompted to allow the upgrade wizard to make changes to your computer, choose 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited. - Linux users: open a Linux console and change directory (
cd) to the directory you saved the '.bin' file and then execute the '.bin' file.
If the '.bin' file is not executable after downloading it, make it executable, for examplechmod a+x atlassian-confluence-5.6.1-x64.bin(specify the exact filename of the installer you downloaded).
- Windows Users: run the .exe file.
- The installation wizard will guide you through the upgrade process. Some things to note:
- When prompted choose Upgrade an existing Confluence installation (for Linux users this is option 3).
- Verify that the Existing Confluence installation directory suggested by the wizard is correct. This is especially important if you have multiple Confluence installations running on the same machine.
- At the 'Back up Confluence directories' step, ensure 'Back up Confluence home' is selected. This will create a .zip backup of the Confluence home and installation directories. This is strongly recommended.
- The installation wizard will notify you of customisations in the Confluence Installation directory. Make a note of these before proceeding as you will need to manually reapply these customisations after the upgrade is complete.
- If you have not already done so, the wizard will prompt you to backup your external database and check plugin compatibility. If your database does not support online backups you will need to stop the installation wizard at this point.
- The wizard will shut down your Confluence instance and proceed with the upgrade. Once complete, it will restart Confluence and you can then launch Confluence in your browser to confirm the upgrade was successful.
During the upgrade the wizard will migrate following from your existing Confluence installation:
- TCP port values in your
server.xmlfile. - Custom values in your
confluence-init.properties(confluence.home property).
If you are using an Oracle or MySQL database, you'll need to copy the jdbc driver jar file from your existing Confluence installation directory to confluence/WEB-INF/lib in your new installation directory.
Other configurations or customisations (including CATALINA_OPTS parameters in your setenv.sh / setenv.bat files and any other modifications in the server.xml file) are not migrated during the upgrade and need to be reapplied manually. See below for more information.
Additional steps when customisations are present
The installation wizard's ability to notify you about customisations will depend on how your existing Confluence instance was installed:
- If your current Confluence instance was installed using the installer, the wizard will check the entire Confluence Installation directory.
- If your current Confluence instance was installed manually it will only check the
confluencesubdirectory of the Confluence Installation directory. The installation wizard will not notify you of modifications in any other directory, for example modifications to start-up scripts under thebindirectory or modifications to theserver.xmlfile (such as an SSL configuration).
If customisations are present you will need to perform the following steps after the upgrade is complete:
- Stop the upgraded Confluence instance.
- Reapply the customisations to the relevant files in the upgraded Confluence Installation directory.
- Restart the upgraded Confluence instance.
We strongly recommend you test your customisations in a test instance prior to upgrading your production instance as changes may have been made to Confluence that make your customisations unsuable.
Troubleshooting
Did something go wrong?
If you need to retry the upgrade, you must restore your pre-upgrade backups first. Do not attempt to run an upgrade again, or start the older version of Confluence again after an upgrade has failed.
Some common issues encountered while upgrading:
- Cannot proceed with upgrade because license has expired
If your licence has expired and was not renewed and reapplied before upgrading you will receive errors during the upgrade process. See upgrading beyond current license period for information on how to resolve this problem. - Unable to proceed with upgrade because of a conflict with anti virus
Some anti-virus or other Internet security tools may interfere with the Confluence upgrade process and prevent the process from completing successfully, particularly if you run Confluence as a Windows service. 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. - Database does not support online backups
The upgrade wizard will prompt you to backup your database using your database's backup utilities. If your database does not support online backups, stop the upgrade process, shut down Confluence, perform your database backup and then run the installer again to continue with the upgrade. - Upgrade is taking a very long time
If you have a very large database (i.e. database backups take a very long time to complete), setting theconfluence.upgrade.recovery.file.enabledsystem property to false will speed up the upgrade process. It should be used only when there is a process to back up database and verify the backup before performing an upgrade.
You can also refer to the Upgrade Troubleshooting guide in the Confluence Knowledge Base, or check for answers from the community at Atlassian Answers.