Upgrading Confluence Manually
This document describes the procedure for upgrading to the latest version of Confluence on Windows or Linux manually (not using the upgrade wizard). See Upgrading Confluence to upgrade using the installer and upgrade wizard.
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 moving to a different database you should upgrade first and then follow the procedure outlined in Migrating to Another Database.
- Are running Confluence in a cluster 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 H2 Database for more information.
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.
Step 4 Upgrade Confluence in your production environment
- Download the appropriate archive file.
- Shut down Confluence.
- Extract (unzip) the files to a directory (this will be your new installation directory, and must be different to your existing installation directory)
Note: There are some known issues with unzipping the archive on Windows. We recommend using 7Zip or Winzip. Update the following line in the
<Installation-Directory>\confluence\WEB-INF\classes\confluence-init.propertiesfile to point to your existing Confluence home directory.# confluence.home=c:/confluence/dataFor example if your existing Confluence home directory is
c:\confluence\myhomethe file will read:confluence.home=c:/confluence/myhome- Copy the JDBC driver jar file from your existing Confluence installation directory to
confluence/WEB-INF/libin your new installation directory.
The JDBC driver will be located in either the<Install-Directory>/common/libor<Installation-Directory>/confluence/WEB-INF/libdirectories. - There are some additional steps you make need to take if:
you are running Confluence as a Windows Service
Click here to expand...If you are running Confluence as a Windows service, go to the command prompt and type:
<Installation-Directory>\bin\service.bat remove ConfluenceIt is vital that you stop and remove the existing service prior to uninstalling the old instance of Confluence. For more information on running Confluence as Windows service, please refer to Start Confluence Automatically on Windows as a Service.
To remove the service installed by the Confluence installer, you'll need to run <confluence auto installer installation folder>\UninstallService.bat.
you use a JIRA application or LDAP for user management
you use Crowd for user management
you are upgrading from Confluence 2.5 or earlier
You are running Confluence on a different port (not the default 8090)
- Start your new Confluence. You should not see the setup wizard.
Additional steps if further customisations are present
If you have customised Confluence (such as an SSL configuration in the server.xml file, or CATALINA_OPTS or JAVA_OPTS parameters in your confluence-init.properties file), you'll 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 newly 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.
You can also refer to the Upgrade Troubleshooting guide in the Confluence Knowledge Base, or check for answers from the community at Atlassian Answers.