mod_jk2 is an old abandoned branch of mod_jk, no longer developed or supported by its creators. You are strongly advised to use mod_jk or mod_proxy instead.

There is now official documentation on configuring Apache and Tomcat that covers the configuration of newer versions of mod_jk.

This page contains brief notes on how to run two Tomcat instances (here assumed to be running JIRA and Confluence) behind Apache, so that both can share port 80, eg.:

http://example.com/jira/
http://example.com/confluence/

Here we use mod_jk2, an Apache module written specifically for Tomcat. A more flexible and generic approach is to use mod_proxy.

Tomcat configuration

Overview

By default, Tomcat serves HTTP requests directly on port 8080. We want Apache to handing incoming HTTP requests, delegate them to a Tomcat instance, and forward the response on to the user.

There are two common ways for Apache to forward on requests to a servlet container like Tomcat:

• Plain HTTP - Apache acts as a proxy (via mod_proxy), passing the raw HTTP text to and from Tomcat with some minor header rewriting. See the Cocoon mod_proxy guide for a full tutorial on this method or Using Apache VirtualHosts for a simpler one. If you do not require https, using mod_proxy as a reverse proxy is a slightly a simpler -- and slightly less performant -- alternative to mod_jk2.
• Via a custom protocol over a port.  In the Apache httpd/Tomcat case, the protocol is AJP13, and Tomcat listens for AJP requests on port 8009 (by default). We use this method below.

Modifying JIRA's Tomcat

Edit conf/server.xml, and make the following changes.

Change context to "/jira"

Change the context path from "":

to "/jira":

Define the AJP listener

Near the bottom before the </Server> tag, add (or uncomment, if using JIRA Standalone) the section:

<!-- To connect to an external web server (typically Apache) -->
<!-- Define a Coyote/JK2 AJP 1.3 Connector on port 8009 -->
<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="8009" minProcessors="5" maxProcessors="75"
enableLookups="true" redirectPort="8443"
acceptCount="10" debug="0" connectionTimeout="0"
useURIValidationHack="false"
protocolHandlerClassName="org.apache.jk.server.JkCoyoteHandler"/>

This tells Tomcat to listen on port 8009 for incoming AJP requests. When you next restart Tomcat, the following messages should print in the logs

[INFO] ServletDispatcher - -Action dispatcher initialized
[INFO] Http11Protocol - -Starting Coyote HTTP/1.1 on port 8080
[INFO] ChannelSocket - -JK2: ajp13 listening on /0.0.0.0:8009
[INFO] JkMain - -Jk running ID=0 time=17/106  config=/home/jturner/jk2_example/jira1/conf/jk2.properties

Modifying Confluence's Tomcat

Follow the same process on the Confluence Tomcat's conf/server.xml, changing the context from "" to "/confluence", and setting the AJP port to 8010 instead of 8009, so it doesn't conflict with JIRA's.

You will need to avoid two more port conflicts to get Confluence's Tomcat working alongside JIRA's:

1. On the first line, change the shutdown port from 8005:

   <Server port="8005" shutdown="SHUTDOWN" debug="0">

   to something else:

   <Server port="8006" shutdown="SHUTDOWN" debug="0">

1. Locate the HTTP connector:

   <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8080" minProcessors="5"

Change the port from 8080 to 8081. As we will be connecting through Apache soon anyway, you may wish to comment out this HTTP connector eventually, but for now it is useful for debugging.

Start JIRA and Confluence

You are now set to go. In the bin/ directories of JIRA and Confluence, run startup.sh to start up JIRA and Confluence. Check the logs/catalina.out file of each to ensure there are no errors. If the modifications have been successfully applied, you will be able to access JIRA and Confluence from http://localhost:8080 and http://localhost:8081 respectively.

Install Apache and mod_jk2

Install Apache2 (or Apache):

Install mod_jk2

RPMs may be found on rpmfind.net.

You may need to edit Apache's httpd.conf to load the mod_jk module. For Apache 2 on Debian, jk2.load must be symlinked into /etc/apache2/mods-enabled (the .deb does this automatically).

mod_jk seems to expect its configuration file to reside in $apache_root/conf/workers2.properties. On my system, I created /etc/apache2/conf/workers2.properties. Your workers2.properties should contain:

# Define the JIRA Tomcat's channel
[channel.socket:localhost:8009]
info=Ajp13 forwarding over socket
tomcatId=localhost:8009

# Define the JIRA Tomcat's worker
[ajp13:localhost:8009]
channel=channel.socket:localhost:8009

# Define the Confluence Tomcat's channel
[channel.socket:localhost:8010]
info=Ajp13 forwarding over socket
tomcatId=localhost:8100

# Define the Confluence Tomcat's worker
[ajp13:localhost:8010]
channel=channel.socket:localhost:8010

# URL mappings

[uri:/jira/*]
info=Map the whole webapp
group=ajp13:localhost:8009

[uri:/confluence/*]
info=Map the whole webapp
group=ajp13:localhost:8010


[shm:]
info=Scoreboard. Required for reconfiguration and status with multiprocess servers
file=/var/run/apache2/jk2.shm
size=1000000
debug=0
disabled=0

The hierarchy is Channel -> Group -> URL mapping. For two Tomcat instances, we define a channel and group each.

Now restart Apache (with apache2ctl restart or /etc/init.d/apache2 restart), and try accessing http://localhost/jira and http://localhost/confluence.

Assuming everything works, you may now wish to edit the conf/server.xml's and disable the HTTP connector (ports 8080 and 8081).

Troubleshooting.

If something has gone wrong:

• Check that JIRA and Confluence are running correctly by accessing them directly through http://localhost:8080 and http://localhost:8081
• Try telnetting to the AJP ports to verify that they are listening:

  jturner@teacup:~$ telnet localhost 8009
  Trying 127.0.0.1...
  Connected to localhost.
  Escape character is '^]'.

  and

  jturner@teacup:~$ telnet localhost 8010
  Trying 127.0.0.1...
  Connected to localhost.
  Escape character is '^]'.

• Check the Apache logs for mod_jk errors. You can turn up mod_jk debugging by adding the following to the start of workers2.properties:

  [logger]
  level=DEBUG