Upgrading Confluence Standalone Distribution

This document tells you how to upgrade from one version of Confluence to a later version. These
instructions apply to the Standalone Distribution of Confluence. The Standalone distribution includes
Apache Tomcat as the standalone application server.

If you want to upgrade an EAR/WAR distribution deployed on your own existing application server,
please refer to Upgrading Confluence EAR-WAR Distribution instead.

Please also check the following before you start using this guide:

• The version of Confluence that you will be upgrading to. Refer to the documentation home page
to verify the latest Confluence version and to find documentation for older versions.
• The supported platforms for the version that you will be upgrading to. Please see the Supported
Platforms page for the version of Confluence that you will be upgrading to, as well as the End of
Support Announcements for Confluence.
• If you are running Confluence on a cluster, please see Upgrading a Confluence Cluster instead
of this document.
Upgrading to Confluence 3.2?
If so, please review the Confluence 3.2 Upgrade 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.

Before you Start

Changing your Database?
If you are planning to change to a different database, we recommend that you complete the
Confluence upgrade first. Then follow the instructions on migrating to a different database.
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 upgrade
notes for any major versions you are skipping. It is important to read these upgrade notes as
there might be specific changes between Confluence versions that could affect your Confluence
instance. The upgrade notes pages for recent major versions of Confluence are accessible from
the Upgrade Notes Overview page. (Each upgrade notes page is a 'child' of its respective release
notes page.)
If you are upgrading from a version of Confluence prior to 2.5.5, the upgrade notes information
is located under a heading on the release notes pages.
 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 Installing the Confluence EAR-WAR Edition
for your specific application server, to see if there is anything extra you will need to do to get
Confluence running. For example:
• Resin 3 users will need to update web.xml.
7. If you are using an external database, familiarize yourself with all known issues for your specific
database. Also 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. Back up 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.
Tip: Another term for 'Home directory' would be 'data 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. Back up your database. Perform a manual backup of your external database before proceeding
with the upgrade, and double check that the backup was actually created properly. If you are not
a database expert, or unfamiliar with the backup-restore facilities of your database, you should try
to restore the backup to a different system to ensure the backup worked, before proceeding. This
recommendation is not specific to Confluence usage but just common sense: Surprisingly many
companies, even banks, get in trouble for broken database backups.
The 'embedded database' is the HSQLDB database supplied with Confluence for evaluation
purposes, you don't need to back it up since it is stored in the home directory. But you should not
use this database for production systems anyway, so if you happen to accidentally still use
HSQLDB in a production system, please migrate to a proper database before the upgrade.
3. Back up 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'.
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

If you are migrating servers or migrating databases, perform those operations in separate steps.

To install Confluence, unzip the new Confluence installation zip file 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 Standalone 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>, e.g. confluence-2.9.2-std.
• In the rest of this document, we will refer to this as the <Installation-Directory>.
• If you decide to change the location from the default, make sure that you choose a
different location from your existing Confluence installation, because legacy files may
cause problems if you install the new Confluence version into an existing 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.
• You can read more about the Confluence Home directory.
• Make sure you have first backed up this directory, as instructed above.
• Open the confluence-init.properties file in a text editor such as Notepad.
• Scroll to the bottom and find this line:
1.# 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 running Confluence as a Windows service, use <Installation-
Directory>\bin\tomcat5w.exe to remove and re-install the Tomcat service. Or use 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 the
Start Confluence automatically on Windows as a Service topic.
7. To remove the service installed by Confluence Auto Installer, you need to run the
<confluence auto installer installation folder>\UninstallService.bat.
8. If you are using an external database (i.e. not the embedded HSQLDB database supplied for
evaluation purposes), copy the jdbc driver jar file from your old Confluence Standalone
installation to the new Confluence Standalone installation. The jdbc driver jar file in the old
Confluence Standalone installation should be located in either the <Install-
Directory>/common/lib or <Installation-Directory>/confluence/WEB-INF/lib
directories. Once you have identified this file, copy it to either the <Install-Directory>/lib
or <Installation-Directory>/confluence/WEB-INF/lib directories of your Confluence
3.x installation.
9. If you have delegated your user management to JIRA, LDAP, Crowd, 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" />

10. If you have delegated your user management to Crowd, you will also need to copy the Crowd
client library and configuration files from your old Confluence installation to your new Confluence
installation: <Installation-Directory>/confluence/WEB-INF/lib/crowd-
integration-client-X.X.X.jar and <Installation-Directory>/confluence/WEB-
INF/classes/crowd.properties. If you need more information, please refer to the Crowd
documentation.
11. Consider any adjustments you need to make to customisations and special configurations, as
described below.
Your new version of Confluence may not function correctly or could encounter problems or
errors if these are not implemented.
12. Start your new version of 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.
13. During the startup process Confluence will create any missing database indexes. If you created
any database indexes on your own, please check those afterwards and remove those that
duplicate the indexes added by Confluence. Just in case you run into any errors which prevent
Confluence from starting up, you can set the system property
hibernate.hbm2ddl.skip_creating_missing_indexes to true to skip automatic index
creation.
 14. 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.
15. 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.

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 had previously connected your Confluence installation to an external database via a JNDI
datasource or you implemented SSL, edit your new web.xml file and and copy over any relevant
modifications from your old web.xml file, which relate to these customisations.
• 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.
• If you had changed the Confluence interface text, you will need to pull over the
ConfluenceActionSupport.properties file.
 • If you were using a custom SSO authenticator or the utility to Automatically Add LDAP users to
the confluence-users Group, change seraph-config.xml to the correct authenticator.

Checking for Known Issues and Troubleshooting the

Confluence Upgrade
• Check for known issues. Sometimes we find out about a problem with the latest version of
Confluence after we have released the software. In such cases we publish information about the
known issues in the Confluence Knowledge Base. Please check the important technical
advisories on the front page of the Knowledge Base and follow the instructions to apply any
necessary patches.

• Did you encounter a problem during the Confluence upgrade? Please refer to the guide to
troubleshooting upgrades in the Confluence Knowledge Base.