Documentation for Confluence 5.4.
Documentation for Confluence OnDemand and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

Apache Tomcat is the only application server supported for Confluence. To move Confluence from an application server (e.g. WebSphere) to Tomcat using the same database, follow the instructions below.

Please note, you cannot simply copy the WAR file or expanded WAR directory from an old Confluence EAR/WAR version in the old application server to Tomcat. This will not work.

Follow these instructions:

1. Before You Start

 

  1. The following instructions will only work if you are running the same major version of Confluence on both application servers. If you are running different major versions of Confluence, you will need to upgrade Confluence before you can switch to Tomcat.
  2. Note that you need current software maintenance, as the process for changing application servers involves installing Confluence or Confluence EAR-WAR.
  3. If the environment (e.g. the database system, the operating system and so on) that you are running Confluence in has changed, please ensure it still complies with the Confluence System Requirements.
  4. If you are using an external database, familiarise 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.
  5. Note any customisations that you have made to Confluence, e.g. enabled/installed plugins, modified layouts, custom themes, etc. You will need to reapply these after you have switched to Tomcat. You can view the list of customisations in the Reapplying Customisations section below.
  6. We recommend that you do not run any other applications in your Tomcat application server that is running Confluence, to prevent performance issues.

2. Backing Up

 

Before you switching to Tomcat, 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 are using the embedded HSQLDB database supplied for evaluation purposes, the database files are also stored in this directory.
    (tick) 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 check that the backup was 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 that the backup worked before proceeding. This recommendation is not specific to Confluence usage, but it is good practice to ensure that your database backup is not broken.
    (info) 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) 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. Switching Application Servers

 

  1. Install Confluence on your new application server. We recommend that you install Confluence (from the zip file) as it is preconfigured with Tomcat. If you want more control over the installation process, you can install Confluence EAR-WAR on Tomcat however this requires more manual configuration.
    Regardless of which method you choose, as part of the installation process:
  2. Copy the following files from your old Confluence installation to your new one:
    • {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\confluence-init.properties
    • {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\atlassian-user.xml
    • {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\osuser.xml (copy this over if you are using JIRA user management)
    • {CONFLUENCE_INSTALL}\confluence\WEB-INF\classes\seraph-config.xml (copy this over if you using custom SSO)
    • {CONFLUENCE_INSTALL}\confluence\WEB-INF\web.xml (copy this over if you have previously modified it, e.g. to configure a datasource)
  3. Make sure you shutdown the old server before you startup the new one.
  4. If you are running the new application server on a different machine to the old one, carry out the following actions as soon as you start the new server:
  5. If you have applied special settings to their Confluence server and/or Confluence look and feel, you will need to reapply these customisations as described in below.

4. Applying Customisations

 

After switching to Tomcat, you need to review any customisations and other special configurations you previously used for your Confluence instance, and re-apply if necessary. This section also contains some Tomcat-specific customisations that you may wish to considering applying, if you haven't used Confluence with Tomcat before.

Before you apply customisations

Icon

Please ensure that your Confluence installation works correctly on Tomcat without any customisations before you apply any of customisations listed below. This will make it easier to identify problems, if you run into trouble during the switch to Tomcat.

Confluence Server

  • For long-term use, we recommend that you configure Confluence to start automatically when the operating system restarts. For Windows servers, this means configuring Confluence to run as a Windows service.
  • If you are using the Confluence edition 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.

Plugins

  • If you were previously using any plugins, install the latest compatible version and disable any plugins that are incompatible with your new instance of Confluence. The easiest way to do this is to use the Universal Plugin Manager in the Confluence Administration Console.

Look and Feel

  • 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. Please do not just copy your VM (velocity) files across. Ensure that Confluence works without your custom layouts then apply the layout via the Confluence Administration console.

Performance

  • If the load on your Confluence instance is high, you may need more simultaneous connections to the database. Read more about this in the Performance Tuning guide.
  • 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. See How to Fix Out of Memory Errors by Increasing Available Memory for more information.

Advanced Customisations

  • If you were previously running Confluence over SSL, you will need to reapply your configuration as described in Running Confluence Over SSL or HTTPS.
  • If you were using a custom SSO authenticator, change seraph-config.xml to the correct authenticator.
  • If you had changed the Confluence interface text, you will need to copy over the ConfluenceActionSupport.properties file.
  • If you had previously modified the Confluence source code, you will need to reapply your changes to the new version.

5. Testing Confluence

 

Make sure you test Confluence on the new server before deploying it in production.

The Working with Confluence Logs document contains the locations for the application logs, if you need to refer to them.

  • No labels

4 Comments

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

    Since people using HSQLDB are those who are using Confluence Standalone, I thought this was a bit redundant.

    But after a rethink, it's important to mention it because we don't know if they are evaluating with EAR/WAR version with HSQLDB.

    2. Back up your database. Does the database need to be backed up?

    Theoretically, they don't need to do this if they are moving to a new App Server (does not change anything in the database side).

    But we never know what the customers will do, so I think it's important to backup their schema.

    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). Do customers need to back up their installation director?

    This is the same as number two.

    They don't really need to make a backup but we should mention this for the sake of preventing them from shooting themselves.

    They do need to copy old configuration (eg. layout, atlassian-user.xml, confluence-init.properties, etc.) over to the new installation.

    One question from customer that I sometimes get is: do I need to run build.sh for Confluence if deploying in Tomcat as EAR/WAR?

    The answer is Tomcat can deploy Confluence whether it's exploded or not. So it's not necessary to run build.sh. But, I don't have a good answer over which one is better.

  2. Backup database in Step 2:

    if you happen to accidentally still use HSQLDB in a production system, please migrate to a proper database before the upgrade.

    Let's link to migrate to an external database doc: Migrating to Another Database

    For layout files, perhaps it's worth mentioning that if they have custom layout in installation they should not copy these first. In an upgrade scenario, these files often are no longer the same. Copying the layout files directly can cause a problem. It's best to apply the customisation later on after confirming the vanilla configuration works first. Applying customisation directly to vm files is not recommended as it can be a nightmare to maintain and troubleshoot. Instead, layout customisation should be applied via Confluence Admin console.

    I also didn't add in any instructions about running build.sh. If you don't think it's necessary, it's best not to include it.

    Ok

    1. For Step 3. Switching Application Servers:

      The customer may be using JIRA User management. In this case they may need to copy their osuser.xml setting as well.

      If they have modified <confluence>/confluence/WEB-INF/web.xml previously, they may need to copy this as well.

      Customers may be using custom SSO, so they may need to copy seraph.xml.

  3. Anonymous

    Copying the layout files directly can cause a problem. It's best to apply the customisation later on after confirming the vanilla configuration works first. Applying customisation directly to vm files is not recommended as it can be a nightmare to maintain and troubleshoot. Instead, layout customisation should be applied via Confluence Admin console.-Gucci D Gold brand name bags