This document describes the standard, recommended procedure for upgrading to Confluence 4.3 Use this procedure when upgrading from Confluence version 3.5 or later on Windows or Linux.

Notes:

  • Clustered Confluence. The automatic installer/upgrader does not support upgrading clustered installations of Confluence. See Upgrading a Confluence Cluster.
  • Upgrading from an early version of Confluence. If you are upgrading from a version earlier than Confluence 3.5, you will need to use 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 will need to use manual upgrade procedure. See Upgrading Confluence Manually.

Upgrading to Confluence 4.3?

If so, please review the Confluence 4.3 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:

Unable to render {include} The included page could not be found.

Upgrade Overview

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

  1. Backs up the Installation and Home Directories of the existing Confluence installation to be upgraded.
  2. Installs Confluence 4.3 whilst migrating the following from your existing Confluence installation to the new Confluence 4.3 installation:
    • TCP port values in your existing Confluence installation's server.xml file. (warning) 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.

(info) 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

  1. Download the Confluence 'Windows Installer' (.exe) file (for the new version of Confluence) from the Confluence Download Center.
  2. Run the '.exe' file to start the upgrade wizard.
    (info) 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.
  3. At the 'Upgrading Confluence?' step, choose the 'Upgrade an existing Confluence installation' option.
  4. In the 'Existing Confluence installation directory' field, specify the Confluence Installation Directory of your Confluence installation to be upgraded.
    (info) 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.
  5. 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.
      (info)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. (info)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.
        (warning) 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.
  6. 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.

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

Upgrading Confluence on Linux

  1. 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.
  2. Open a Linux console and change directory (cd) to the '.bin' file's directory.
    (warning) 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)
  3. Execute the '.bin' file to start the upgrade wizard.
  4. When prompted to choose between creating a new Confluence installation or upgrading an existing installation, choose the 'Upgrade an existing Confluence installation' option.
  5. Specify the Confluence Installation Directory of your Confluence installation to be upgraded.
    (info) 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.
  6. 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.
      (info) 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. (info)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.
        (warning) 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.
  7. 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.

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.

(warning) 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.

Except where otherwise noted, content in this space is licensed under a Creative Commons Attribution 2.5 Australia License.