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

Find the upgrade path that works for your current version of Confluence and the version you plan to upgrade to.

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:

Step 2 Upgrade Confluence in a test environment

We strongly recommend you recreate your production instance and test the upgrade in this cloned environment.

  1. Create a snapshot of your current production Confluence environment on a test server - see Moving Confluence Between Servers for how to do this.
  2. Follow the steps below to perform the upgrade on your cloned environment.
  3. 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/classes directory 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

  1. Download the appropriate archive file.
  2. Shut down Confluence.
  3. 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.
  4. Update the following line in the <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.properties file to point to your existing Confluence home directory.

    # confluence.home=c:/confluence/data

     For example if your existing Confluence home directory is c:\confluence\myhome the file will read:

    confluence.home=c:/confluence/myhome
  5. Copy the JDBC driver jar file from your existing Confluence installation directory to  confluence/WEB-INF/lib in your new installation directory. 
    The JDBC driver will be located in either the <Install-Directory>/common/lib or <Installation-Directory>/confluence/WEB-INF/lib directories. 
  6. 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 Confluence

      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.

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

        Click 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:

      • <Installation-Directory>/confluence/WEB-INF/classes/osuser.xml

      • <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml

    • you use Crowd for user management

        Click 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/osuser.xml

      • <Installation-Directory>/confluence/WEB-INF/classes/atlassian-user.xml (if you are upgrading from Confluence 2.2 or later).

      • <Installation-Directory>/confluence/WEB-INF/classes/crowd.properties
    • you are upgrading from Confluence 2.5 or earlier

        Click here to expand...

      If you are upgrading from Confluence 2.5.5 or earlier and are copying the existing atlassian-user.xml file from your previous instance, make sure the hibernate cache parameter in this file is enabled, to avoid performance issues. 

      <hibernate name="Hibernate Repository" key="hibernateRepository" description="Hibernate Repository" cache="true" />

      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.xml file to include your ports

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

  1. Stop the upgraded Confluence instance.
  2. Reapply the customisations to the relevant files in the newly upgraded Confluence Installation directory.
  3. 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.

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport