This document outlines the procedures you need to follow to upgrade from one version of Confluence to another. You can download the latest version of Confluence from here. Note that only users with current software maintenance may perform the upgrade.

If you are running Confluence on a cluster, please see Upgrading a Confluence Cluster instead of this document.

Step 1:  Backing up

Before you begin the upgrade, you must backup the following:

  1. Your Confluence Home Directory (see Important Directories and Files for how to locate this).
  2. Your Confluence Install Directory (if you are using Confluence Standalone) or your Confluence webapp (if you are using Confluence EAR-WAR).
  3. If you are not using the embedded database, perform a manual backup of your database before proceeding with the upgrade.

Step 2: Things you need to check

  1. 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).
  2. If you are not using the embedded database, check the Database Configuration Guide for your specific database, to see if there is anything extra you will need to do to get Confluence running. E.g. If you are not using the embedded database, and are running Confluence Standalone, you would have added a datasource to the following file: <Install-Directory>/conf/server.xml.
  3. If you are not using Confluence Standalone, 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. E.g.:
  4. Note which plugins are currently installed/enabled.

Step 3: Performing the upgrade

There are two ways to perform the upgrade.

  • Method One is the most convenient and will allow you to reuse your existing Confluence Home Directory and database.
  • However, if you are upgrading from a 1.x version to a 2.x version of Confluence, you must use Method Two.


Method One: Point the new installation to your existing Confluence Home

  1. Confluence をシャットダウンします。
  2. Download Confluence Standalone or Confluence EAR-WAR. (For information about the difference between the two, please see the Installation Guide.)
  3. Create a new Confluence Install directory (e.g. 'confluence-2.4.3-std') and unzip the downloaded file into it. It is recommended that you include the version number in the directory name, and avoid putting spaces in the path. Windows users may wish to use C:\confluence\confluence-X.Y.Z (where 'X.Y.Z' is the version you downloaded, e.g. '2.4.3').
  4. Edit the <Install-Directory>\confluence\WEB-INF\classes\confluence-init.properties file and update 'confluence.home' to point to your existing Confluence Home directory (make sure you have first backed this up as described in 'Step 1' above). For more details about editing the confluence-init.properties file, please see 'Set Your Home Directory' in the Standalone Installation Guide.
  5. If you are using Confluence EAR-WAR, and 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.
  6. If you are not using the embedded database, copy the jdbc driver jar file from your old Confluence installation to the new Confluence installation:
    • If you are using Confluence Standalone, the jdbc driver jar is in the <Install-Directory>/common/lib directory.
    • If you are using Confluence EAR-WAR, the location of the jdbc driver jar will depend on your particular application server.
  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:
    • <Install-Directory>/confluence/WEB-INF/classes/osuser.xml.
    • <Install-Directory>/confluence/WEB-INF/classes/atlassian-user.xml (if you are upgrading from Confluence 2.2 or later).
  8. If you are using Confluence EAR-WAR, restart your application server.
  9. Launch your new Confluence. (You should not see the Setup Wizard.)
  10. Access Confluence via your web browser and confirm that all your spaces and pages are present and everything looks normal. You should see the new Confluence version number in the footer.

(info) If Method One is unsuccessful, try Method Two. Occasionally, starting afresh will fix the problem.

Method Two: Export and restore to a brand new instance

  1. From Confluence, go to Administration -> Backup & Restore and create a manual backup that includes attachments.
  2. Confluence をシャットダウンします。
  3. Download Confluence Standalone or Confluence EAR-WAR. (For information about the difference between the two, please see the Installation Guide.)
  4. Create a new Confluence Install directory (e.g. 'confluence-2.4.3-std') and unzip the downloaded file into it. It is recommended that you include the version number in the directory name, and avoid putting spaces in the path. Windows users may wish to use C:\confluence\confluence-X.Y.Z (where 'X.Y.Z' is the version you downloaded, e.g. '2.4.3').
  5. Create a new Confluence Home directory as described in 'Set Your Home Directory' in the Standalone Installation Guide.
  6. If you are not using the embedded database, copy the jdbc driver jar file from your old Confluence installation to the new Confluence installation:
    • If you are using Confluence Standalone, the jdbc driver jar is in the <Install-Directory>/common/lib directory.
    • If you are using Confluence EAR-WAR, the location of the jdbc driver jar will depend on your particular application server.
  7. If you are not using the embedded database, create a new, empty database on your database server.
  8. Start up your new installation of Confluence.
  9. Access Confluence via your web browser and run the Setup Wizard. Note: Do not point Confluence to your old database.
    • If you were using the embedded database, selected 'Embedded database' when prompted by the Setup Wizard.
    • If you were not using the embedded database, specify the new, empty database that you created on your database server in step 6.
  10. When asked to restore existing data, specify the backup created in step 1.
  11. If you have delegated your user management to JIRA, LDAP or any other external user management system, shut down Confluence and copy the following files from your old Confluence installation to your new Confluence installation:
    • <Install-Directory>/confluence/WEB-INF/classes/osuser.xml.
    • <Install-Directory>/confluence/WEB-INF/classes/atlassian-user.xml (if you are upgrading from Confluence 2.2 or later).
  12. Access Confluence via your web browser and confirm that all your spaces and pages are present and everything looks normal. You should see the new Confluence version number in the footer.



次のステップ

  • 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 were previously running Confluence on a particular port, edit your new  <Install-Directory>\conf\server.xml  file as described in Change listen port for Confluence Standalone.
  • 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.
  • 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 were previously 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 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 <Install-Directory>\bin\setenv.sh or setenv.bat file, you may want to make the modifications in your new installation. The parameters are specified in the JAVA_OPTS variable.

トラブルシューティング

  • After upgrading by Method Two, there may be problems viewing pages that use Shortcut Links. If these occur, please install the patch from http://jira.atlassian.com/browse/CONF-7739.
    The failures will show up in the logs as entries like this: 
    java.lang.ClassCastException: java.lang.String
	at com.atlassian.confluence.renderer.DefaultShortcutLinksManager.getShortcutLinkConfig(DefaultShortcutLinksManager.java:65)
	at com.atlassian.confluence.links.linktypes.ShortcutLink.<init>(ShortcutLink.java:23)
	at com.atlassian.confluence.links.ConfluenceLinkResolver.makeShortcutLink(ConfluenceLinkResolver.java:188)
	at com.atlassian.confluence.links.ConfluenceLinkResolver.createLink(ConfluenceLinkResolver.java:128)
  • If you need assistance with the upgrade, please log a support request at http://support.atlassian.com.

Related documentation

Confluence Installation Guide
Important Directories and Files
Site Backup and Restore
Database Configuration
 

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