Using Apache with mod_jk

Introduction

The Apache web server is often used in front of an application server to improve performance in high-load environments. Mod_jk allows request forwarding to an application via a protocol called AJP. Configuration of this involves enabling mod_jk in Apache, configuring a AJP connector in your application server, and directing Apache to forward certain paths to the application server via mod_jk.

Mod_jk is sometimes preferred to mod_proxy because AJP is a binary protocol, and mod_jk supports fallback and load balancing. (Please note that you need a clustered license for Confluence to function properly in a load-balanced environment.)

The scope of this documentation is limited to configuring the AJP connector in Tomcat 5.x. Other application servers may support AJP connectors; please consult your application server documentation for instructions on how to configure it.

The configuration below assumes your Confluence instance is accessible on the same path on the application server and the web server. For example:

The AJP connection of the application server is set to: app-server.internal.example.com:8009.

Configuring mod_jk in Apache

The standard distribution of Apache does not include mod_jk. You need to download it from the JK homepage and put the mod_jk.so file in your Apache modules directory.

# Put this after the other LoadModule directives
LoadModule jk_module modules/mod_jk.so

# Put this in the main section of your configuration (or desired virtual host, if using Apache virtual hosts)
JkWorkersFile conf/workers.properties
JkLogFile logs/mod_jk.log
JkLogLevel info

JkMount /confluence worker1
JkMount /confluence/* worker1

Configuring workers.properties

Create a new file called 'workers.properties', and put it in your Apache conf directory. (The path for workers.properties was one of the configuration settings above.)

worker.list=worker1

worker.worker1.host=app-server.internal.example.com
worker.worker1.port=8009
worker.worker1.type=ajp13

Tomcat 5.x configuration

In Tomcat 5, the AJP connector is enabled by default on port 8009. An absolutely minimal Tomcat server.xml is below for comparison. The relevant line is the Connector with port 8009 – make sure this is uncommented in your server.xml.

<Server port="8005" shutdown="SHUTDOWN">
  <Service name="Catalina">

    <!-- Define a HTTP/1.1 Connector on port 8080 -->
    <Connector port="8080" />

    <!-- Define an AJP 1.3 Connector on port 8009 -->
    <Connector port="8009" protocol="AJP/1.3" />

    <Engine name="Catalina" defaultHost="localhost">
      <Host name="localhost" appBase="webapps">
	<Context path="/confluence" docBase="/opt/webapps/confluence-2.2/confluence"/>
        <Logger className="org.apache.catalina.logger.FileLogger"/>
      </Host>
    </Engine>
  </Service>
</Server>

Points to note:

• the Connector on port 8009 has protocol of "AJP/1.3". This is critical.
• the Context path of the Confluence application is "/confluence". This must match the path used to access Confluence on the web server.
• we recommend keeping your application Contexts outside the server.xml in Tomcat 5.x. The above example includes them for demonstration only.

Improving the performance of the mod_jk connector

The most important setting in high-load environments is the number of processor threads used by the Tomcat AJP connector. By default, this is only 15, and you should increase it to match Apache's maxThreads setting (256 by default):

<Connector port="8009" minProcessors="5" maxProcessors="256" protocol="AJP/1.3" />

Ensuring UTF-8 compatibility

If you have problems downloading attachments with non-ASCII characters in the filename, add the following to your Apache configuration:

JkOptions +ForwardURICompatUnparsed

And specify UTF-8 as the URIEncoding in the AJP connector configuration:

<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8" />

These settings are discussed further on Configuring Tomcat's URI encoding.

More information

The Tomcat JK website has complete documentation on workers.properties and Apache configuration. You can also find information there on how to use mod_jk with IIS.

Alternatives

If you're not happy with mod_jk, or find it too difficult to configure, you can:

• use mod_proxy, which works with any application server, and together with mod_proxy_html allows complex URL rewriting to deal with different application paths on the web server and the application server.