Switching to Apache Tomcat

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.

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

3. Switching Application Servers

  1. Install Confluence on your new application server. We recommend that you download Confluence as a stand alone archive (rather than using the installer). 
    (warning) Important: At this stage, just unzip the standalone file to a location of your choice - this will be your new installation directory. You should not start Confluence until directed to in step 3 below. 

  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. Start Confluence (make sure you shutdown the old server before you start up 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

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 setenv.bat file, you may want to make the modifications in your new installation. The parameters are specified in the CATALINA_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.

Was this helpful?

Thanks for your feedback!

4 Archived comments

  1. User avatar

    Roy Hartono

    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.

    21 May 2010
  2. User avatar

    Roy Hartono

    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

    25 May 2010
    1. User avatar

      Roy Hartono

      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.

      25 May 2010
  3. User avatar

    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

    31 Aug 2011
Powered by Confluence and Scroll Viewport