The content on this page relates to platforms which are not supported by JIRA. Consequently, Atlassian can not guarantee providing any support for it. Please be aware that this material is provided for your information only and using it is done so at your own risk. |
This page describes how to integrate an Apache HTTP Server (httpd) with JIRA (via mod_proxy), such that 'httpd' forwards requests on to JIRA and responses back to the user. This is useful if you already have 'httpd' serving web pages on port 80 (e.g. http://mycompany.com), and wish to integrate JIRA as just another URL (eg. http://mycompany.com/jira).
You can only configure JIRA to respond to a single URL, and your Base URL setting must match the URL end users are requesting. You cannot (for example) have a different hostname or URL for internal and external users. This is especially important for JIRA 4.0 or higher, as any mismatch between the Base URL and the URL requested by the end user will cause problems with dashboard gadgets. |
This documentation describes a straightforward implementation of mod_proxy. If you require a more complex solution, refer to Apache HTTP Server Version Documentation and, if necessary, consult with someone in your organisation who is knowledgeable in the configuration of 'httpd'. |
Step 1: Configure JIRA's application server
Here we assume you are using the 'recommended' JIRA distribution (i.e. not JIRA WAR), which includes Tomcat. First, we need to edit Tomcat's conf/server.xml file, and set the context path:
<Server port="8005" shutdown="SHUTDOWN">
<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false">
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
....
Here we have set the context path to /jira, assuming JIRA will be running on http://mycompany.com/jira/.
Restart Tomcat, and ensure you can still access JIRA normally (eg. at http://localhost:8080/jira/).
Note: if you want Tomcat responsible for all URLs, specify a blank context path with path="" — not path="/" .
Turn JIRA's GZip compression OFF (since there will be no benefit from GZip compression once proxying is implemented, and in fact GZIP has been reported to cause performance problems in this situation).
Step 2: Configure 'httpd'
Assuming an Apache HTTP Server version 2 installation, the following needs to be done:
Enable mod_proxy and mod_proxy_http
The exact steps will be specific to your operating system. Refer to the Apache documentation for your operating system. On Debian/Ubuntu it is done as follows:
teacup:/etc/apache2# a2enmod proxy_http Enabling proxy as a dependency Module proxy installed; run /etc/init.d/apache2 force-reload to enable. Module proxy_http installed; run /etc/init.d/apache2 force-reload to enable. teacup:/etc/apache2#
Configure mod_proxy
Here we create a config snippet for JIRA, in sites-available/jira-mod_proxy:
teacup:/etc/apache2# cd sites-available teacup:/etc/apache2/sites-available# cat > jira-mod_proxy <Proxy *> Order deny,allow Allow from all </Proxy> ProxyRequests Off ProxyPreserveHost On ProxyPass /jira http://localhost:8080/jira ProxyPassReverse /jira http://localhost:8080/jira teacup:/etc/apache2/sites-available# teacup:/etc/apache2/sites-available# a2ensite jira-mod_proxy Site jira-mod_proxy installed; run /etc/init.d/apache2 reload to enable. teacup:/etc/apache2/sites-available# /etc/init.d/apache2 reload Reloading apache 2.0 configuration.... teacup:/etc/apache2/sites-available#
JIRA should now be integrated with 'httpd'. You should be able to view JIRA at http://localhost/jira (i.e. on port 80).
Terminating an SSL connection at 'httpd'
To add an SSL connection that terminates at 'httpd', using HTTP to connect to JIRA behind it, most of the relevant configuration is:
Listen 443
NameVirtualHost *:443
<VirtualHost *:443>
SSLEngine On
SSLCertificateFile /etc/apache2/ssl/apache.pem
ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/
</VirtualHost>
Notes:
- The path '/jira' must be the same as the context path in Tomcat's conf/server.xml
- The ProxyPreserveHost directive allows Tomcat to know its public hostname and port. Without this, JIRA would redirect the public URL (e.g.
http://mycompany.com/jira/) tohttp://localhost:8080/jira/secure/Dashboard.jspa.
If the links for Printable Version, RSS feeds, Word export and Excel export have incorrect URLs, starting with |
ProxyPreserveHost is only available on Apache HTTP Server version 2. For versions 1.1-1.3.x, you should instead specify proxyName and proxyPort attributes in Tomcat as follows:
<Server port="8005" shutdown="SHUTDOWN">
<Service name="Catalina">
<Connector port="8080"
maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100" connectionTimeout="20000" disableUploadTimeout="true"
proxyName="mycompany.com" proxyPort="80" />
<Engine name="Catalina" defaultHost="localhost">
<Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true">
<Context path="/jira" docBase="${catalina.home}/atlassian-jira" reloadable="false">
<Resource name="jdbc/JiraDS" auth="Container" type="javax.sql.DataSource"
....
If you are using Apache HTTP Server version 1.x, make sure you don't use caching (CacheRoot directive).
Some users have reported problems with user sessions being hijacked when the mod_cache module is enabled. If you have such problems, disable the mod_cache module. Note that this module is enabled by default in some Apache HTTP Server version 2 distributions. |
Troubleshooting
- On Fedora Core 4, people have reported 'permission denied' errors when trying to get mod_proxy (and mod_jk) working. Disabling SELinux (
/etc/selinux/config) apparently fixes this.
- If you are on Mac OS X:
If your gadgets are returning 404 errors, you may need to add the following to Tomcat's <Connector> tag (use port 443 instead of 80 if you're using SSL and terminating it at 'httpd'):
proxyName="your-front-facing-domain.com" proxyPort="80"
Please disable webperfcache,which proxies port 80 by default. A user reported this as the likely cause of JIRA session problems, in the form of users' identities becoming mixed up:
The OSX Servers enable webperfcache by default for Virtual Hosts, which for static content would be great, but for dynamic sites (which ALL of ours are) it is Evil and causes many issues. Of note recently was the jira session issue. Also see :- http://developer.apple.com/documentation/Darwin/Reference/ManPages/man8/webperfcache.8.html http://www.wodeveloper.com/omniLists/webobjects-admin/2005/January/msg00009.html Unfortunately even if you disable webperfcache for a site, if there is a single site enabled then all sites will still proxy through webperfcache with resulting session problems.
- In general, if you are having problems:
- Ensure that JIRA works as expected when running directly from Tomcat on http://localhost:8080/jira
- Watch the log files (usually in /var/log/httpd/ or /var/log/apache2/). Check that you have a LogLevel directive in your httpd.conf, and turn up logging ('LogLevel debug') to get more info.
- Check out the Knowledge Base .
See Also
- Integrating JIRA with Apache using SSL
- Configuring Apache Reverse Proxy Using the AJP Protocol
- For more advanced mod_webapp configurations (eg. SSL), see this mod_proxy guide.