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 > Atlassian Support Tools > Health Check 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 add-on 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.
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.|
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.8
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
We strongly recommend you recreate your production instance and test the upgrade in this cloned 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
Before you begin the Confluence upgrade you must 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 called
confluence-init.properties, which is located inside the
confluence/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 from the Confluence Download Center.
- 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.
For example if your existing Confluence home directory is
c:\confluence\myhomethe file will read:
- 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
- There are some additional steps you make need to take if:
you are running Confluence as a Windows ServiceClick here to expand...
If you are running Confluence as a Windows service, go to the command prompt and type:
It 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 managementClick here to expand...
If you use JIRA or LDAP for user management, copy the following files from your existing installation directory to your new installation directory:
you use Crowd for user managementClick here to expand...
If you are using Crowd for user management, copy the following files from your existing installation directory to your new installation directory:
<Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml(if you are upgrading from Confluence 2.2 or later).
you are upgrading from Confluence 2.5 or earlierClick here to expand...
If you are upgrading from Confluence 2.5.5 or earlier and are copying the existing
atlassian-user.xmlfile from your previous instance, make sure the hibernate cache parameter in this file is enabled, to avoid performance issues.
If you use Crowd for your user management, you do not need to do this.
You are running Confluence on a different port (not the default 8090)Click here to expand...
If you are not running Confluence on port 8090 update
<Installation-Directory>\conf\server.xmlfile to include your ports
- 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 C
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.
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.
Was this helpful?
Thanks for your feedback!