Installing the Confluence EAR-WAR Edition

The Confluence EAR-WAR distribution is intended for deployment into an existing J2EE application server.

To use this method of installation, you need to know how to deploy a web application on an existing application server. If not, please use the Confluence distribution instead.

On this page:

Step 1. Check the System Requirements and Known Issues

1. Please check the Confluence system requirements.
2. In addition to the above requirements, the EAR-WAR distribution requires the Apache Tomcat application server. For more information on Confluence's supported application servers, please refer to our Supported Platforms page.
3. If deploying as an unexploded WAR, Ant 1.3 or later is required. This is bundled with the WAR download.
4. Confluence, the database and application server must use the same character encoding. UTF-8 is recommended.
5. Deploying multiple Atlassian applications in a single Tomcat container is not supported. We do not test this configuration and upgrading any of the applications (even for point releases) is likely to break it. There are also a number of known issues with this configuration (see this FAQ for more information).

   We also do not support deploying multiple Atlassian applications to a single Tomcat container for a number of practical reasons. Firstly, you must shut down Tomcat to upgrade any application and secondly, if one application crashes, the other applications running in that Tomcat container will be inaccessible.

   Finally, we recommend not deploying any other applications to the same Tomcat container that runs Confluence, especially if these other applications have large memory requirements or require additional libraries in Tomcat's lib subdirectory.

6. Read through the Known Issues for Apache Tomcat.

Step 2. Download and Extract EAR-WAR Installation File

This section gives detailed instructions for installing Confluence EAR-WAR edition on an Apache Tomcat 5.5, or 6 server.

1. Download the Confluence EAR/WAR zip file. (You need to click the 'Show all' link to see the EAR/WAR zip file.)
2. Please check your unzip program before extracting the downloaded zip file. Some archive-extract programs cause errors when unzipping the Confluence zip file:
   • Windows users must avoid the Windows built-in unzip utility, as it doesn't extract all the files. Use a third-party unzip program like 7Zip or Winzip.
   • Solaris users will need to use GNU tar to handle the long file names.
3. Extract the downloaded zip file.
4. You have now unzipped your Confluence installation directory, which should contain the version number e.g. confluence-4.0.1 or confluence-4.0.2. This directory will be later referred to as the Confluence installation directory. Inside is a confluence subdirectory, referred to later as the (Exploded) Confluence WAR directory. Record the absolute path to the Confluence WAR directory.

Step 3. Review Application Server Memory Allocation

Confluence requires a maximum heap allocation (Xmx) of at least 256 MB for normal operation. Also, remember to set the maximum PermGen memory allocation (XX:MaxPermSize). See Increasing Application Server Memory.

Do not configure a heap allocation so large that it does not allow enough remaining physical memory for your operating system and other applications on the server. The heap allocation should be large enough for Confluence, but not so large that the memory would be paged to disk during normal operation.

Step 4. Configure confluence-init.properties

1. Inside the Confluence installation directory, edit ...confluence/WEB-INF/classes/confluence-init.properties in a text editor.
2. Now define your Confluence Home directory, by setting the confluence.home property to a directory of your choosing.
   We suggest using different paths for your installation and home directories. This will facilitate upgrades. This is the directory that will contain all of Confluence's configuration, backup and attachment files.
   Tip: Another term for 'Home directory' would be 'data directory'.

Step 5. Edit Tomcat Context Descriptors

1. Create a file called confluence.xml and save in the Catalina/localhost sub-directory of Tomcat. If these directories don't exist you can create them manually.

2. Open your new confluence.xml file and add these lines:

   More on Context Path To run Confluence without a context path, change the path in the Context tag to an empty string (""). If not using a context path, your config will need to be saved as ROOT.xml rather than confluence.xml. In Tomcat, a context path name follows the name of its xml file (except for ROOT.xml where no context path is used. Hence if you wish to change the context path to a different name, change both the context path and the name of the xml file. eg. "/wiki" context path should be saved in file wiki.xml.

3. For docBase, specify the value you noted down earlier.
4. Restart Tomcat, and Confluence should be accessible under /confluence/ on your Tomcat server.
5. Follow the link below to proceed with the setup wizard.

Step 6. Add UTF-8 Encoding

1. Edit conf/server.xml and find the line where the Coyote HTTP Connectoris defined. It will look something like this, possibly with more parameters:

2. Add a URIEncoding="UTF-8"property to the connector:

Step 7. (Optional) Configure Tomcat to Run on a Different Port

See Switching to Apache Tomcat.

Step 8. (Optional) Configure Confluence to Run as a Windows Service

Confluence can be run as a service.

Step 8. Run the Confluence Setup Wizard

Once Confluence is running, open a web browser and visit http://localhost:8080/ (Tomcat default port).

If you changed the port earlier, use the port you specified. Note that the Confluence installer normally uses port 8090 as the default, to avoid conflicts with JIRA (using port 8080).

The Confluence Setup Wizard should appear in your web browser, prompting you to enter your license key. Follow the instructions on screen, and read more guidelines on the Confluence Setup Wizard.

Notes

• Tomcat users, take care not to unzip the Confluence installation into your Tomcat webapps folder, as this may cause Confluence to be deployed more than once. It may cause a Cluster Panic error.
• If you deploy Confluence on an unsupported server, server-related issues cannot be covered by Atlassian technical support. You can try Atlassian Answers for assistance instead.