Cloud
Data Center 5.9
Versions

Switching to Apache Tomcat

Application Server Configuration

On this page

Related content

  • No related content found

Still need help?

The Atlassian Community is here for you.

Ask the community

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 Fix java.lang.OutOfMemoryError in Confluence 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.

Last modified on Dec 2, 2015

Was this helpful?

Yes
No
Provide feedback about this article

Related content

  • No related content found
Powered by Confluence and Scroll Viewport.