This page last changed on Apr 27, 2008 by smaddox.

This document tells you how to upgrade from one version of Confluence to a later version.

These instructions apply to:
  • The EAR-WAR edition of Confluence, deployed on your own existing application server. If you want to upgrade your Confluence Standalone edition, which includes Apache Tomcat as the standalone application server, please refer to Upgrading Confluence Standalone Edition.

Also, please check the new version of Confluence which you are installing. Refer to the documentation home page to verify the latest Confluence version and to find documentation for older versions.

On this page:

Error formatting macro: toc: java.lang.NullPointerException
Upgrading a Cluster or Changing your Database?

Before you Start

  1. Note that you need current software maintenance to perform the upgrade.
  2. Confirm that your license support period is still valid before you try to upgrade.
  3. 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.
  4. Check the release notes for the new version of Confluence you are installing, plus the release notes for any major versions you are skipping, to see if there are any upgrade instructions specific to the new version(s).
  5. 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.
  6. If you are using Confluence EAR-WAR edition, check the Application Server Configuration Guide for your specific application server, to see if there is anything extra you will need to do to get Confluence running. For example:
  7. If you are using an external database, make sure the Confluence database connector principal (the database user login) has sufficient permissions to modify the database schema.
  8. Note which plugins are installed/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 on the respective home pages for these plugins on the Confluence Extension space. Once you have confirmed the availability of compatible versions, you should upgrade your plugins after successfully upgrading Confluence. This can be done via the 'Plugin Repository' in your Administration Console. Please test these first by applying them to the latest Confluence version in a test environment.
  9. 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.

Backing Up

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

  1. Your Confluence Home directory. The Confluence Home directory is the folder where Confluence stores its configuration information, search indexes and page attachments. If you're using the embedded HSQLDB database supplied for evaluation purposes, the database files are also stored in this 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.

  2. Your Confluence Installation directory (if you are using Confluence Standalone) or your Confluence webapp (if you are using Confluence EAR-WAR edition). 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'.
  3. If you are not using the embedded database, perform a manual backup of your external database before proceeding with the upgrade.
    The 'embedded database' is the HSQLDB database supplied with Confluence for evaluation purposes.

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

Performing the Upgrade

The upgrade process allows you to unzip the new Confluence installation into a directory of your choice and then edit the configuration files to point your new installation to your existing data files. Follow these instructions:

  1. Shut down your existing Confluence instance.
  2. Download the Confluence EAR-WAR zip file.
  3. If you are on Windows, please check your unzip program before extracting the downloaded zip file. Some archive-extract programs cause errors when unzipping the Confluence zip file. You should use a third-party unzip program like 7Zip or Winzip. If you do not have one, please download and install one before continuing:
    • 7Zip — Recommended. If in doubt, download the '32-bit.exe' version
    • Winzip
  4. Use your unzip program to unzip the installation file. You should now have a new directory called confluence-<version>.
    • In the rest of this document, we will refer to this as the <Installation-Directory>.
    • Do not use spaces in your directory path.
    • You can read more about the Confluence Installation directory.
  5. Edit the confluence-init.properties file found at: <Installation-Directory>\confluence\WEB-INF\classes\confluence-init.properties
    and update 'confluence.home' to point to your existing Confluence Home directory.
    • Make sure you have first backed up your Home directory.
    • Open the confluence-init.properties file in a text editor such as Notepad.
    • Scroll to the bottom and find this line:
      # confluence.home=c:/confluence/data

    • Remove the '#' and the space at the beginning of this line, so that Confluence no longer regards the line as a comment. The line should now begin with confluence.home.
    • Update the directory name after the = sign, to point to your existing Confluence Home directory.
  6. If you are using Tomcat, you need to update either your confluence.xml or server.xml (depending on where you have defined the Confluence context descriptor) to point to the location of the new Confluence installation (also remember to copy over any customisations such as a tomcat datasource if you have one).
  7. If you have delegated your user management to JIRA, LDAP or any other external user management system, copy the following files from your old Confluence installation to your new Confluence installation:
    • <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).
      If you are upgrading from an earlier version of Confluence (2.5.5 and earlier) and are copying your existing atlassian-user.xml file from your previous instance, please ensure that the hibernate cache parameter in this file has been enabled, to avoid performance related issues. (NOTE: If you use Crowd for your user management, you do not need to do this.):
      <hibernate name="Hibernate Repository" key="hibernateRepository"  description="Hibernate Repository" cache="true" />
      
  8. Restart your application server and start Confluence.
    Please note that Confluence will need to re-index attachments and this can take 5-10 minutes. Please wait until Confluence has finished indexing the attachments before trying to access Confluence via your web browser.
  9. Run the supplied set of SQL statements against your Confluence database to create indexes. These indexes are important for good performance. It is recommended that you pass this file to your DBA to run. If you do not have a DBA, please refer to our basic instructions. If your database reports that any of these indexes already exists, you can safely ignore these warnings.
  10. Visit Confluence in your web browser and log in using a username from your previous Confluence installation. You should be able to log in immediately, without seeing the Setup Wizard.
  11. Take a quick look around your Confluence site to confirm that all your spaces and pages are present and everything looks normal. You should see the new Confluence version number in the page footer.
  12. Consider any adjustments you need to make to customisations and special configurations, as described below.

Reapplying Customisations to your New Confluence

Hint: The steps below are for advanced Confluence users, who have applied special settings to their Confluence server and/or Confluence look and feel

After upgrading your Confluence installation to a later version of Confluence, you need to consider any customisations you have applied to your system and other special configurations:

  • If you had previously installed Confluence/Tomcat as a Windows service, uninstall the service (to ensure that the old Confluence cannot start automatically when the server restarts) and reinstall the new one. For details please see Start Confluence automatically on Windows as a Service.
  • If you are using a Standalone Edition of Confluence and you have previously defined a CATALINA_HOME environment variable, please check that it points to the correct path for the new Confluence Tomcat server.
  • If you were previously running Confluence on a non-standard port, edit your new <Installation-Directory>\conf\server.xml file as described in Change listen port for Confluence Standalone.
  • If you had previously defined a Tomcat datasource, edit your new <Installation-Directory>\conf\server.xml and copy over the datasource definition from your old server.xml.
  • If you were previously using any plugins, install the latest compatible version and disable any plugins that are incompatible with your new version of Confluence. The easiest way to do this is to use the Plugin Repository in the Confluence Administration Console.
  • If you are using any customised themes, please check that they are displaying as expected. Some further customisation may be required to ensure compatibility with your new version of Confluence.
  • If you had previously customised the default site or space layouts, you will need to reapply your changes to the new defaults as described here.
  • If you had previously modified the Confluence source code, you will need to reapply your changes to the new version.
  • If you were previously running Confluence over SSL, you will need to reapply your configuration as described in Adding SSL for Secure Logins and Page Security.
  • If you had previously modified the memory flags (Xms and Xmx) in either the <Installation-Directory>\bin\setenv.sh or the <Installation-Directory>\bin\setenv.bat file, you may want to make the modifications in your new installation. The parameters are specified in the JAVA_OPTS variable.

Troubleshooting the Confluence Upgrade

The Upgrade Guide provides instructions for a standard upgrade, but it's not possible to cover all the variations of installation sizes and versions. If this page does not provide you with a solution for your particular circumstances, please raise a support ticket for help with your upgrade.

Here are some problems that customers have encountered, and the solutions:

  • Problem: If you are upgrading from a Confluence version prior to 2.6, you may see an error message such as: Table 'confluence.bandana' doesn't exist.
    • Workaround: You may need to upgrade to Confluence version 2.5 first before upgrading to the latest version.
    • Explanation: Refer to CONF-9959. The problem occurs when the Confluence license has expired and the confluence.bandana table is missing from the database. If you upgrade to Confluence 2.5 first, this will create the missing table. Then you can upgrade to the later version.
    • Fix: This problem was fixed in Confluence 2.7.2.
  • Problem: If you are upgrading from a Confluence version 2.2.x or earlier to the latest version of Confluence, you may see an error message such as: Upgrade failed: com.atlassian.confluence.extra.leftnavigation.LeftNavSettings.
    • Workaround: You may need to upgrade to Confluence version 2.5 first, before upgrading to the latest version.
    • Explanation: Refer to CONF-11767.
    • Fix: Check CONF-11767 for more updates.
RELATED TOPICS

Upgrading Confluence
Upgrading Confluence Standalone Edition
Confluence Installation Guide
Important Directories and Files
Site Backup and Restore
Database Configuration
How to run a SQL script on your database


indexes.ddl (application/octet-stream)
Upgrade (text/xml)
Document generated by Confluence on Aug 07, 2008 19:08