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
- 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.
- Note that you need current software maintenance, as the process for changing application servers involves installing Confluence or Confluence EAR-WAR.
- 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.
- 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.
- 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.
- 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:
- 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.
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/classesdirectory in your Confluence Installation directory.
- 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.
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.
- 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
- 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:
- If you are connecting to your database via a standard JDBC connection, enter the URL, username and password for your existing database.
- If you are connecting to your database via datasource, use the settings for your existing database when you configure the JDBC datasource in your new server. Refer to the appropriate guide below:
- Copy the following files from your old Confluence installation to your new one:
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)
- Make sure you shutdown the old server before you startup the new one.
- 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:
- 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.
- 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.xmlfile as described in Change listen port for Confluence.
- 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.
- 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 (
Xmx) in either the
<Installation-Directory>\bin\setenv.batfile, you may want to make the modifications in your new installation. The parameters are specified in the
JAVA_OPTSvariable. See How to Fix Out of Memory Errors by Increasing Available Memory for more information.
- 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.