I’ve recently started trialling JIRA – the issue tracking system from Atlassian. Fantastic looking product so far – I’ve done a lot of work with Bugzilla in the past, but it doesn’t compare when it comes to the sizzle that JIRA offers.
The installation documentation is incredibly extensive. Alas, I work in IT which means Murphy’s Law guarantees that the environment I’m given to work in will be unique, complex, and a million miles from a “Standard” setup. Consequently, I was dealing with reverse proxies, apache front-ends, https issues and more besides! 
One issue that I did spend a while on was this one: http://jira.atlassian.com/browse/JRA-19051. Basically, JIRA has problems when installing on Tomcat 6 if you want to use a Context that is multi-level. So, something like “/servlets/JIRA” rather than “/JIRA”.
The fault is actually with Sitemesh that JIRA makes use of. Tomcat 6 uses a naming standard based on hashes as separators to specify a multi-level context. So, in the example above, the context XML and exploded WAR file is stored as “servlets#JIRA”. Unfortunately, this confuses Sitemesh who tries to drill into the expected Context directory structure and complains that directory “servlets” does not exist.
The issue linked to above is still unresolved and was raised in September 2009, so I suspect it’s probably a pretty low priority. I was able to work around it however by inserting the “<context>” stanza for JIRA in the main server.xml file rather than in a file of its own.
While this isn’t the preferred Tomcat way of doing things (any changes I make will require a Tomcat restart), doing the Context entry this way allows you to use the path attribute, where you specify the full Context path. Using a standalone Context file, you can’t use this attribute – it is inferred from the (special, hash-separated) file name.
I also used the docBase attribute to point to the exploded WAR file. I placed the exploded WAR file under the standard webapps directory, but nested to match the multi-level context path (so, something like …/webapps/servlets/jira, rather than the more Tomcat-6-normal /webapps/servlets#jira).
This was enough to get me up and running. I suspect it might also be possible to do something using an Apache proxy, whereby Tomcat thinks it is running single level contexts (/jira) and Apache proxies the requests to those single levels (so it converts requests for /servlet/jira to simply /jira). Unfortunately this wasn’t possible in the environment I was running in, so I haven’t pursued it any further.
Hopefully this run-down is helpful to anyone else who hits this issue!