This page last changed on Mar 16, 2007 by david.soul@atlassian.com.

This document will assist you in adding Confluence to your existing JIRA Standalone.

Step 0 - Consider alternatives

This guide is for experts only. If you run into any difficulties with this process, Atlassian technical support may provide limited assistance outside of helping users switch to running Confluence Standalone separately.

Before embarking on this process, consider whether you could not rather run JIRA and Confluence in separate Tomcat instances running behind an Apache frontend server (see guides for Confluence and JIRA). There are some benefits to keeping them separate:

  • Each app can be restarted without affecting the other.
  • If one webapp hangs for any reason (eg. running out of memory), it doesn't affect the other.
  • Any problems can be debugged more easily. Logs are separate and product-specific, rather than everything going to catalina.out. Thread and heap dumps are smaller and more relevant.
  • It reduces the likelihood of jar conflicts (eg. jars that must be installed in common/lib), particularly if you later want to install a third webapp not from Atlassian.

Offsetting this is the extra complexity of having to run Apache.

If you wish to proceed, please follow these instructions:

Step 1 - Download and extract WAR

  1. Download the Confluence WAR file
  2. Extract the downloaded zip file. It should extract to a folder called confluence-<version>. Inside this folder you'll find a folder called "confluence". Make a note of the absolute path to this directory (as you will need to use it later). Note: Do not copy the confluence folder to the webapps folder inside tomcat - this may cause Confluence to be deployed more than once.

Step 2 - Configure confluence-init.properties

  1. Open confluence/WEB-INF/classes/confluence-init.properties in a text editor
  2. Set the confluence.home property to a directory of your choosing. This is the directory that will contain all of Confluence's configuration, backup and attachment files.

Step 3 - Edit tomcat context descriptors

If you are deploying to JIRA version 3.3 or higher:

  1. Create a file called confluence.xml in your JIRA standalone's conf/Catalina/localhost directory (if you have set up a different hostname for your JIRA tomcat instance, please specify that instead of localhost)
  2. Open confluence.xml and add these lines:
    <Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="true"> <Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/> </Context>
  3. For docBase specify the value you noted down earlier. This is the full path to the confluence folder in your confluence-<version> installation folder, not the confluence home folder. It should look like: c:/<path to confluence installation>/confluence-<version>/confluence.

Otherwise (for older versions of JIRA):

  1. Open conf/server.xml in a text editor
  2. Find the block that begins: <Context path="" docBase="../atlassian-jira" debug="0" reloadable="true"> and ends with </Context> block.
  3. After the </Context>, append the following:
    <Context path="/confluence" docBase="c:/applications/confluence-2.1.3/confluence" debug="0" reloadable="true"> <Logger className="org.apache.catalina.logger.FileLogger" prefix="atlassian-confluence." suffix=".log" timestamp="true"/> </Context>
  4. For docBase specify the value you noted down earlier. This is the full path to the confluence folder in your confluence-<version> installation folder, not the confluence home folder. It should look like: c:/<path to confluence installation>/confluence-<version>/confluence.
  5. Remove the commons-logging-1.0.4.jar file from the confluence\WEB-INF\lib directory

Do not delete the existing Jira <Context> block. Insert the code above after the Jira <Context> block.

Step 4 - Modify your setenv.sh/bat (ONLY IF YOU ARE RUNNING A SUN MICROSYSTEMS JVM) 

  1. Open JIRA's bin/setenv.sh/bat (.sh on unix, .bat on windows) in a text editor.
  2. Find the line that says: "... JAVA_OPTS=... " and add -XX:MaxPermSize=128m to its end.

The Java Virtual Machine sets aside a portion of memory as the "permanent space", for objects that it never expects to have to garbage-collect. Because JIRA and Confluence are both quite large applications, it is possible that this permanent space will be filled up. Increasing the application heap size will not help, because the permanent generation size is a separate setting. 

This flag is only supported on JVM's created by Sun Microsystems. If you include this flag while running another vendors JVM (such as JRocket, or IBM's JVM) they will not start.

Step 5 - Restart the Server

  1. Shut down, and then restart the standalone server
  2. Confluence should now be accessible on the same server as your existing JIRA standalone, under the confluence directory.
    For example, if your JIRA is running at http://jira.example.org:8080/, Confluence will be running on http://jira.example.org:8080/confluencereuse

When setting up the Confluence database do not reuse the JIRA database. Create a new database for Confluence.

Troubleshooting

When I try to send a test mail from Confluence, I get javax.mail.NoSuchProviderException: smtp

In some circumstances, Confluence will be unable to send email after being deployed in the same application-server as JIRA. If, when you try to send a test mail from the administration tool, you get the error: "javax.mail.NoSuchProviderException: smtp", please follow these instructions to fix it.

I have installed JIRA and Confluence in some other application server than Tomcat

These instructions only apply to the standalone Tomcat version of JIRA. Other application servers have not been tested in this configuration, and users have specifically reported difficulties deploying the two applications together in Orion Server and JBoss. We hope to resolve these issues soon.

Confluence is slow, and dumps enormous amounts of information to its logfiles

If you are seeing a large amount of DEBUG logging output, then ensure that you have removed the commons-logging-1.0.4.jar file from the confluence\WEB-INF\lib directory

Document generated by Confluence on May 01, 2007 19:28