Below are some important notes on upgrading to Confluence 3.0.1. Confluence 3.0.1 is a recommended upgrade which fixes some security flaws as well as other bugs. For more details, please read the Confluence 3.0.1 Release Notes.

On this page:

Upgrade Notes

If you have customised the cache settings in your installation of Confluence (e.g. for performance reasons), then please read ALL information on this page before upgrading to Confluence 3.0.1 or to a 'standard edition' of Confluence. This page also contains important information for customers who are upgrading their installation of Confluence to version 2.6 or later from September 2009.

ClusterManager for Non-Clustered Licenses causes Critical Errors

The ClusterManager in the non-clustered (i.e. you do not have a clustered license) implementations of Confluence 3.0.1 and Confluence 3.0.2 does not perform any locking (e.g. for job synchronisation). As a result, your Confluence instance may crash due to certain jobs being executed concurrently when they shouldn't be.

We strongly recommend that you upgrade to Confluence 3.1 or later to avoid this issue, if possible. If you wish to install or upgrade to a non-clustered implementation of Confluence 3.0.1 or 3.0.2, you must apply the patch attached to CONF-17136 after upgrading.

Introduction of 'Standard' and 'Clustered' editions

Oracle Coherence Licensing Change:

  • Due to a license agreement change between Atlassian and Oracle over the Coherence technology, from September 2009, Confluence will be made available in two editions:
    • Standard Edition — Confluence with Ehcache's caching technology (available to customers with non-clustered Confluence licenses).
      (warning) If you are currently running a clustered installation of Confluence, please do not upgrade it with a standard edition of Confluence.
    • Clustered Edition — Confluence with Oracle's Coherence clustering and distributed caching technology (available to customers with Confluence clustered licenses only).
  • For more information, please refer to the Coherence License Changes document.
  • In standard editions of Confluence, Ehcache replaces the local caching functionality previously provided by the Coherence technology.

Confluence 3.0.1 is the first Confluence version to be released in two editions 'standard' and 'clustered'.

Also, from September 2009:

  • Standard editions will be released for each previous major version of Confluence back to 2.6. These will be:

    • Available as Confluence versions 2.10.4, 2.9.3, 2.8.3, 2.7.4 and 2.6.3.
    • Available to customers with non-clustered Confluence licenses.

  • The remaining previous versions of Confluence currently available from our download page (from 2.6 to 3.0 inclusively), will be re-released as clustered editions and will only be available to customers with Confluence clustered licenses.

  • The installation files for all versions of Confluence prior to 2.6 (which are no longer supported) will be removed from the Atlassian web site and will no longer be available for download and installation.

Confluence Caching Layer Changes

Due to the caching layer changes in the 'standard editions' of Confluence, you will need to reapply any cache customisations made to your cache sizes and/or cache configuration file, if all three of the following points are applicable:

  • You have implemented cache customisations to your Confluence installation's cache sizes (either via the Administration Console or cache configuration file).

  • You have an existing installation of Confluence 3.0 or earlier (excluding the 'standard edition' versions) and will be upgrading to Confluence 3.0.1 or later (or one of the earlier standard editions).

  • Your Confluence installation is using a non-clustered Confluence license.

If you customised your Confluence instance's cache settings via the Administration Console, please refer to the Reapplying Cache Size Modifications via the Administration Console section below.

If you customised your Confluence instance's cache settings by modifying the cache configuration file, please refer to the Reapplying Cache Configuration File Modifications section below.

Reapplying Cache Size Modifications via the Administration Console

To reapply your cache size modifications via the administration console:

  1. Before you upgrade, use the procedure described on the Cache Statistics page to open the 'Cache Statistics' section of the Administration Console in the 'Advanced' view.

  2. Print out this view or save a copy of the web page for later reference. (This contains your existing individual cache settings.)

  3. After upgrading Confluence, view the 'Cache Statistics' section of your upgraded Confluence installation in the 'Advanced' view.

  4. Use the same procedure describe on the Cache Statistics page to re-adjust the size of each cache based on the previous settings that you had printed out (or saved).

Reapplying Cache Configuration File Modifications
To maintain your existing cache configuration file settings, you will need to transfer any cache customisations you have implemented in the Coherence cache configuration file (confluence-coherence-cache-config.xml) to the relevant entries in the Ehcache cache configuration file (ehcache.xml).

Each cache has a cache-mapping element in the Coherence file (of which there is an equivalent cache element in the ehcache.xml file). Unfortunately, copying across your customisations is not quite a straightforward process because the Coherence file defines several 'caching schemes' to store the actual cache values, which in turn are referenced by the cache-mapping elements. In contrast, the ehcache.xml file does not support caching schemes and a cache's values are expressed explicitly in separate parameters of a cache element.

To convert your Coherence cache configuration file customisations across to the equivalent Ehcache file:

  1. Open both the confluence-coherence-cache-config.xml and ehcache.xml files in a text editor. These files are located in the <confluence-home>/config directory.
    (info) If you implemented your customisations in a version of Confluence prior to 3.0, you will most likely find the confluence-coherence-cache-config.xml file in the <confluence-install>/confluence/WEB-INF/classes directory.
  2. In the customised confluence-coherence-cache-config.xml file:

    1. Identify the caching schemes that were customised in this file and make a note of the values of all its child elements.
      (info) Typically, each caching scheme is located inside a local-scheme element and all of these are enclosed within the cache-schemes element, which appears towards the end of this file.
    2. Note each customised caching scheme by the content of its scheme-name element.
    3. For each cache-mapping element (which typically appears towards the top of this file), identify if it has a scheme-name element whose content matches one noted in the previous step and if so, make a note of its associated cache-name element.
  3. In the ehcache.xml file:

    1. Identify each cache element whose 'name' parameter matches the cache-name elements noted in step '2c'.
    2. Using the mappings table below, apply the values noted in step '2a' to the appropriate parameters of the cache elements identified in the previous step ('3a').

Mappings table showing how elements of the Coherence cache configuration file map to parameters of the equivalent Ehcache file.

Coherence Element

Ehcache Attribute

high-units

maxElementsInMemory

expiry-delay > 0s

timeToIdleSeconds - Use this attribute for expiry delays greater than 0s along with the eternal attribute set to 'false'

expiry-delay = 0s

eternal - For expiry delays of 0s, set this attribute to 'true'.

Upgrade Procedure

If you are already running a version of Confluence, please follow these instructions to upgrade to the latest version:

  1. Before you upgrade, we strongly recommend that you back up your confluence.home directory and database.

  2. If your version of Confluence is earlier than 3.0.1, read the release notes and upgrade guides for all releases between your version and the latest version. In particular:
  3. Download the latest version of Confluence.

  4. Follow the instructions in the Upgrade Guide.

Useful Plugins

Before installing an add-on (also called a plugin) into your Confluence site, please check the add-on's information page to see whether it is supported by Atlassian, by another vendor, or not at all. See our guidelines on add-on support.
  • No labels

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