This document describes the procedure for upgrading to the latest version of Confluence, on Windows or Linux.

Notes:

Recommended upgrade paths

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	Manually upgrade to 2.7.4 then upgrade to 3.5.17, and follow paths below.
2.8 to 3.4	Manually 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.x	Upgrade directly to the latest version of Confluence 5.

Upgrading from an early version of Confluence. If you are upgrading from a version earlier than Confluence 3.5, you must use the manual upgrade procedure. See Upgrading Confluence Manually.
Moving to a different OS, database or file location. If you are changing the operating system that will run Confluence, the database it is using, or the location of its files, you must use the manual upgrade procedure. See Upgrading Confluence Manually.
Clustered Confluence. The automatic installer/upgrader does not support upgrading clustered installations of Confluence. See Upgrading a Confluence Cluster.

Upgrading to Confluence 5.0?

If so, please review the Confluence 5.0 Release Notes for important information about this version of Confluence.

Also, we strongly recommend that you check the upgrade notes for every major version of Confluence that you are skipping, since there might be specific changes between Confluence versions that could affect your Confluence installation. The upgrade notes for recent major versions of Confluence are accessible from the Upgrade Notes Overview page.

Finally, please check the Supported Platforms page to ensure that your Java version, operating system, application server, database and browser are supported for this release of Confluence. The End of Support Announcements for Confluence page has important information regarding supported platforms.

On this page:

Before you Start

Changing your Database?

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 Confluence EAR-WAR edition, check Installing the Confluence EAR-WAR Edition to see if there is anything extra you will need to do to get Confluence running.
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 are installed and 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 via the 'Plugins' menu in your Administration screens, and selecting Confluence Upgrade Check. This will tell you which plugins have an updated version which is compatible with your target upgrade version. 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.

Backing Up

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

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 are 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. 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. 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

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.

XML imports

Importing an old XML backup file to a new major version (for example, Confluence 3.5 to Confluence 4.0) is not recommended. Please recreate your production instance in a test environment first.

2. Perform the upgrade on your cloned environment.

3. 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.

Upgrade Overview

The upgrade feature of the Linux and Windows Installers automates the following tasks for you:

Backs up the Installation and Home Directories of the existing Confluence installation to be upgraded.
Installs Confluence 5.1 whilst migrating the following from your existing Confluence installation to the new Confluence 5.1 installation:
- TCP port values in your existing Confluence installation's server.xml file. Be aware that other configurations or customisations in this file are not migrated during upgrade, and will need to be re-applied.
- Custom values in your existing Confluence installation's confluence-init.properties (confluence.home property) and setenv.sh / setenv.bat files (JAVA_OPTS parameters)

The upgrade feature detects and notifies you of any files in the confluence subdirectory of your existing Confluence Installation Directory which have been deleted, added or modified from a 'default' Confluence installation. This informs you of any customisations you will need to migrate manually over to your upgraded Confluence installation directory. Note that modifications to files in directories other than confluence will not be detected when you upgrade to Confluence 4.0, for example any modifications to start-up scripts under the bin directory will not be detected. The next time you upgrade (e.g. to version 4.0.1) the the upgrade feature will cover modifications across the whole Confluence Installation Directory.

Please Note:

The upgrade process requests that you conduct a backup of your database using your database's backup utilities. If your database does not support online backups, you can stop the upgrade process, shut down Confluence, perform your database backup and then restart the upgrade process to continue on.
If you have made customisations to your server.xml file or any other files in your Confluence installation directory which are not handled by the upgrade wizard, these must be re-applied manually.
If your attachments and index files are located outside your Confluence Home Directory, then backups of these directories must be performed manually.

Performing the Upgrade

Refer to the appropriate upgrade instructions below for your operating system:

Upgrading Confluence on Windows

Download the Confluence 'Windows Installer' (.exe) file (for the new version of Confluence) from the Confluence Download Center.
Run the '.exe' file to start the upgrade wizard.
If a Windows 7 (or Vista) 'User Account Control' dialog box requests if you want to allow the upgrade wizard to make changes to your computer, specify 'Yes'. If you do not, the installation wizard will have restricted access to your operating system and any subsequent installation options will be limited.
At the 'Upgrading Confluence?' step, choose the 'Upgrade an existing Confluence installation' option.
In the 'Existing Confluence installation directory' field, specify the Confluence Installation Directory of your Confluence installation to be upgraded.
The upgrade wizard will attempt to find an existing Confluence installation and use its location to pre-populate this field. However, always verify this location, particularly if you have multiple Confluence installations running on the same machine.
During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
1. At the 'Back up Confluence directories' step, ensure the 'Back up Confluence home' option is selected. This creates 'zip' archive file backups of your existing Confluence Installation and Confluence Home Directories in their respective parent directory locations.
  Please Note:
  - Choosing this option is strongly recommended!
2. At this point, the upgrade wizard notes any customisations in your existing Confluence Installation Directory which it cannot automatically migrate to your upgraded Confluence installation. If you are notified by the installer about any files containing such customisations, please make a note of the locations of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded Confluence installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the Confluence Installation Directory. Please Note: when upgrading from the version that was not installed by the installer the customisations can only be detected in the confluence subdirectory of your existing Confluence Installation Directory. Modifications to files in directories other than confluence will not be detected when you upgrade, for example, modifications to conf/server.xml. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover modifications across the whole Confluence Installation Directory.
3. At the 'Upgrade Check List' step, back up your external database and check that any non-bundled plugins will be compatible with your upgraded Confluence version. You may have already conducted the latter (in step 5 of the Before You Start section above).
4. Upon clicking 'Next', your existing Confluence installation will be shut down if it is still running. The upgrade wizard will then:
  1. Back up your existing Confluence installation.
  2. Delete the contents of the existing Confluence Installation Directory.
  3. Install the new version of Confluence to the existing Confluence Installation Directory.
  4. Starts your new (upgraded) Confluence installation.
    If you noted any files that contain customisations which must be migrated manually to your upgraded Confluence installation (above), then:
    1. Stop the upgraded Confluence installation.
    2. Migrate the customisations from these files into the upgraded Confluence Installation Directory.
    3. Restart the upgraded Confluence installation.
At the last step of the upgrade wizard, select the option to launch the upgraded Confluence installation in a browser so you can check the upgrade.
If you are upgrading to Confluence 5.0: If the global default language of your Confluence site is not English, you will need to install a patch in the form of a plugin. For more information, please refer to this article in our knowledge base: Nothing Happens when Users Click on The "Create" Button.

Congratulations, you have completed upgrading your Confluence installation on Windows!

Upgrading Confluence on Linux

Download the appropriate Confluence 'Linux 64-bit / 32-bit Installer' (.bin) file that suits your operating system (for the new version of Confluence) from the Confluence Download Center.
Open a Linux console and change directory (cd) to the '.bin' file's directory.
If the '.bin' file is not executable after downloading it, make it executable, for example:
chmod a+x atlassian-confluence-X.Y.bin
(where X.Y represents your version of Confluence)
Execute the '.bin' file to start the upgrade wizard.
When prompted to choose between creating a new Confluence installation or upgrading an existing installation, choose the 'Upgrade an existing Confluence installation' option.
Specify the Confluence Installation Directory of your Confluence installation to be upgraded.
The upgrade wizard will attempt to find an existing Confluence installation and will provide its location as a choice. However, always verify this location, particularly if you have multiple Confluence installations running on the same machine.
During subsequent steps of the upgrade wizard, you will be prompted to specify or do the following options:
1. Choose the option to back up Confluence's directories. This creates 'zip' archive file backups of your existing Confluence Installation and Confluence Home directories in their respective parent directory locations.
  Please Note:
  - Choosing this option is strongly recommended!
  - At this point, the upgrade wizard notes any customisations in your existing Confluence Installation Directory which it cannot automatically migrate to your upgraded Confluence installation. If you are notified of any files containing such customisations, please make a note of the locations of these files as you will need to manually migrate their customisations (which are not mentioned in the overview above) to your upgraded Confluence installation. One relatively common customisation that the upgrade wizard cannot automatically migrate is an SSL configuration defined in the conf/server.xml file of the Confluence Installation Directory. Please Note: when upgrading from the version that was not installed by the installer the customisations can only be detected in the confluence subdirectory of your existing Confluence Installation Directory. Modifications to files in directories other than confluence will not be detected when you upgrade, for example, modifications to conf/server.xml. However the next time you upgrade (e.g. to version 4.1.1) the upgrade feature will cover modifications across the whole Confluence Installation Directory.
2. At the 'Upgrade Check List' step, back up your external database and check that any non-bundled plugins will be compatible with your upgraded Confluence version. You may have already conducted the latter (in step 5 of the Before You Start section above).
3. Upon proceeding, your existing Confluence installation will be shut down if it is still running. The upgrade wizard will then:
  1. Back up your existing Confluence installation.
  2. Delete the contents of the existing Confluence installation directory.
  3. Install the new version of Confluence to the existing Confluence installation directory.
  4. Starts your new (upgraded) Confluence installation.
    If you noted any files that contain customisations which must be migrated manually to your upgraded Confluence installation (above), then:
    1. Stop the upgraded Confluence installation.
    2. Migrate the customisations from these files into the upgraded Confluence Installation Directory.
    3. Restart the upgraded Confluence installation.
The last step of the upgrade wizard provides you with a link to launch the upgraded Confluence installation in a browser, so you can check the upgrade.
If you are upgrading to Confluence 5.0: If the global default language of your Confluence site is not English, you will need to install a patch in the form of a plugin. For more information, please refer to this article in our knowledge base: Nothing Happens when Users Click on The "Create" Button.

Congratulations, you have completed upgrading your Confluence installation on Linux!

Upgrade Check List

The upgrade wizard requests that you perform the following tasks before it actually commences the upgrade of your existing Confluence installation.

Back Up Your External Database

Perform a backup of your external database (using your database's native backup tools) and verify that the backup was created correctly.

If your database's native backup tools support 'online backups' (i.e. which would typically create a 'snapshot' of your Confluence database while the database is still in use), you can leave the upgrade wizard running while you perform the database backup and then continue on with the wizard after verifying that the database backup was created correctly.
If your database's native backup tools do not allow you to perform an 'online backup' of your Confluence database, you should:
1. Quit the upgrade wizard now.
2. Use your database's native backup tools to perform an 'offline backup' of your Confluence database and verify that this backup was created correctly.
3. Re-run the Linux / Windows Installer to start the upgrade wizard again and continue from where you left off.
If you are using HSQLDB as the Confluence internal database, please note that this should be used for evaluating Confluence only. If you happen to accidentally use the HSQLDB database for a production system, quit the upgrade wizard now and use the Migrating Confluence Between Servers procedure to upgrade Confluence.

Inconsistent database backups may not restore correctly! If you are unfamiliar with your database's native backup/restore facilities, then test your database backup's integrity by doing the following:

1. Restoring the database backup to a different (test) system,
2. Connecting a test instance of your current Confluence version to this restored database.

Alternatively, use the Migrating Confluence Between Servers procedure to upgrade Confluence instead.

Check Plugin Compatibility

If you have installed any 3rd-party Confluence plugins (i.e. not included in Confluence), please verify that they will be compatible with the version of Confluence you are upgrading to. You can find a plugin's compatibility information from the the plugin's home page 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 by navigating to Browse > Confluence Admin > Configuration > Plugins.

Page tree