How to migrate Confluence from an EAR or WAR Distribution to a Standalone version

Still need help?

The Atlassian Community is here for you.

Ask the community

As noted in our End of Support Announcements for Confluence, Confluence 5.7 and above no longer offers an EAR/WAR distribution. In order to upgrade to Confluence 5.7 or above, you must first migrate to the standalone version of Tomcat. 

Before Proceeding

Before proceeding, ensure that you:

  • Shut down Confluence
  • Complete a full database backup
  • Complete a full backup of your installation directory, and your home directory

You may also wish to apply these changes in a test environment before applying them to production.

To perform this migration there are two possible approaches with both sharing some common elements.

Download the Confluence Server or DataCenter Standalone file

Download the standalone version of Confluence that matches your current version. It is recommended to avoid changing versions during the migration process. For example, if you are currently using Confluence 5.6.6 EAR/WAR, you would need to download "5.6.6 Server - Standalone (ZIP Archive)" or "5.6.6 Server - Standalone (TAR.GZ Archive)". 

Conventions used in this guide

For brevity, there are several conventions used in this guide:

  1. <confluence-install> refers to the location that you'll be installing your standalone version of Confluence to
  2. <tomcat-home> refers to the location of your existing Tomcat 

Two Possible Migration Options

Option 1: Create a new standalone installation folder and reconfigure the home directory to the existing home folder

If using the Server standalone product, you could update the home folder pointer of a new Confluence installation to the existing home folder location:

  1. Extract the contents of the archive you downloaded to a location of your choice. This will be the new installation directory for the Confluence standalone instance.
  2. Stop the existing EAR/WAR instance.
  3. Edit the new installation's <confluence-install>/confluence/WEB-INF/classes/ file and set the confluence.home variable to the location of your existing home directory (do not include the trailing slash):

Note for Windows Administrators

 When specifying a home directory path, you must use double backslashes for each directory separator:

confluence.home = C:\\Program Files\\Atlassian\\Application Data\\Confluence

(info) Customizations from the EAR/WAR distribution

While it's technically possible to start Confluence Standalone after setting the home directory, most instances will have existing configurations that will need to be migrated across. Some examples of customizations that may have been made to an instance include:

  • Tomcat connectors, which define what port(s) Confluence will listen on are defined in <confluence-install>/conf/server.xml
    • This file can also contain SSL configuration, if you choose to terminate SSL at Tomcat
    • This file can also contain JNDI database and mail resources as well
  • Any customizations to Velocity Templates, which are stored in <confluence-install>/confluence/decorators

For Linux based EAR/WAR distributions of Confluence, Java Virtual Machine (JVM) settings are defined in <confluence-install>/bin/

For Windows based EAR/WAR distributions of Confluence, the location of Java Virtual Machine (JVM) settings will depend on your existing installation. See the Windows sections of Configuring System Properties for an explanation.

Option 2: Install a new standalone instance and migrate via a site XML backup and restore

If using either the Server or Data Center standalone products, you could migrate the content from the EAR/WAR instance by way of a site XML backup and restore:

  1. Extract the contents of the archive you downloaded to a location of your choice. This will be the new installation directory for the Confluence standalone instance.
  2. Create a new database for this new standalone instance.
  3. Create a site XML backup from the EAR/WAR instance.
  4. Stop the existing EAR/WAR instance.
  5. Install and setup the newly downloaded standalone instance and configure it to use the new database.
  6. Once the instance is setup and basic functionality has been tested, import the site XML backup created from step 3.
  7. Reinstall all user installed third party apps.

Last modified on Jun 11, 2020

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.