Search the JIRA 5.0.x Beta and RCs Documentation:

Index
Downloads (PDF, HTML & XML formats)
Other versions

This documentation relates to JIRA 5.0.x Beta and RCs only.
The latest official version is JIRA 4.4.x
If you are using JIRA 4.4.x either view this page in the JIRA 4.4.x documentation or visit the JIRA 4.4.x documentation home page.
Skip to end of metadata
Go to start of metadata

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:

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:

Configure mod_proxy

Here we create a config snippet for JIRA, in sites-available/jira-mod_proxy:

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:

Notes:

If the links for Printable Version, RSS feeds, Word export and Excel export have incorrect URLs, starting with localhost:8080/jira instead of http://mycompany.com/jira , ensure that ProxyPreserveHost is set to On.

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:

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'):

    • 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:

  • In general, if you are having problems:
    1. Ensure that JIRA works as expected when running directly from Tomcat on http://localhost:8080/jira
    2. 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.
    3. Check out the Knowledge Base .

See Also

23 Comments

Hide/Show Comments

  1. Feb 23, 2010

    Andrew Leonard

    To terminate SSL connections at an Apache instance listening on 443 back-proxying requests to JIRA (plain HTTP on 8080), I needed to edit my server.xml as follows (info from Atlassian support):

    The "scheme", "proxyName" and "proxyPort" attributes are added and JIRA needs to be restarted; the Apache Tomcat Configuration Reference has more information. Adjust proxyName's value to match your site.

    1. Jan 11, 2011

      Anonymous

      You don't have to use proxyName, it works with schema and proxyPort only. BTW if you receive a "ssl_error_rx_record_too_long" on firefox, you forgot to set proxyPort.

      1. Jan 14, 2011

        Andrew Leonard

        I believe proxyName is a requirement if the Apache server (or other proxy) is running on a different host from Tomcat; I haven't tested running both on the same host without proxyName being set, but including it certainly causes no harm.

  2. Mar 05, 2010

    Markus Khouri

    Do not forget to change the Base URL used in email notifications; if you do forget, the links in emails will not use your new configuration.  For details on changing this option, see http://confluence.atlassian.com/display/JIRA/Configuring+JIRA+Options

  3. May 25, 2010

    Phil Miller

    I have a site hosted on Apache 2.2 with some private content available only via URLs beginning with https://servername.example.com/private/. I wanted to proxy JIRA 4.1.1 beneath that path as /private/jira, to get all of the various policies around it without duplication. To do this, I tried a lot of crap with mod_proxy_html with a lot of frustration and partial results. I eventually figured out the 'proper' way to do this without all sorts of scary rewriting:

    server.xml
    apache-site.conf

    Note that the requested path that Apache sees, /private/jira matches the requested path presented to JIRA, and that will prefix everything coming back from it. This spares the need to do any rewriting of text as part of the proxying.

    1. Sep 25, 2011

      Anonymous

      Thank you Phil

      I added your extra line and it worked (we're not using SSL).

       "proxyName="servername.example.com" proxyPort="80" 

      Thanks for your help

      -Mike

  4. Jun 29, 2010

    Richard Mahn

    I am wondering if I understand this correctly, that even though this guide shows how to get JIRA running under Apache, which is what I want, it seems that its stand-alone server still has to be running, is that right?  My whole reason for switching to Apache is that I found that just getting a simple page served from JIRA from my website took soooo much time, so much more time than pages from Website CMS, such as Drupal.  It also seemed that the JIRA server wouldn't respond at all, or even be down, even though the Apache server, which runs on a dedicated server for our site, is up (and yes, I did put a startup script for Jira in /etc/init.d)

    My question is: why is it I still need to run bin/startup.sh in the jira program directory?  Doesn't this defeat the purpose of moving to Apache to serve the pages?  Why can other apps like ActiveCollab or Drupal use Apache without needing a script/server to run?  Or am I missing something?

    1. Aug 20, 2010

      Anonymous

      Right, the standalone server has to run at any time.

      I believe you mix up Apache HTTPD and Apache Tomcat. HTTPD is a "plain" webserver for serving static files, whereas Tomcat is an application server that serves applications (dynamic content). The important thing to understand here is that Jira, just as most other web-apps, has its own lifecycle; it works even if you don't request a page. Thus Jira comes with it's own bundled Apache Tomcat, which you must start with the script in /etc/init.d.

      The only purpose of this document is to describe how to hide Jira behind an Apache HTTPD, so that to the end user the folder /jira looks like it is part of the regular site.

  5. Jul 06, 2010

    sunfish

    Hi,
    For my case,
    proxyName="jira.example.com" proxyPort="80" />
    or something like the line above seems needless ,when using those and change context path attribute to -> path="/jira" ,
    all resources would not load on my v4.1.2#531 (standalone), even without using apache proxy (xampp : apache 2.2 ),
    just http://localhost:jiraport/jira, got bulks of /s/..blabla..css 404 not found error, since using this would not work ,the  problem seems in server.xml 

    Delete proxyName and proxyPort just work fine  without proxy and with proxy, same thing happens to my confluence installation

  6. Jul 12, 2010

    Mike Haney

    @Richard - no, you still need the Tomcat server running, since Tomcat is the application server where the pages are actually generated, database queries are performed, etc.  Most people front their Tomcat servers with an HTTP server for several reasons:

    1) The HTTP server in Tomcat and other app servers is very basic, and won't support advanced caching, performance, and security features like a full-fledged HTTP server

    2) For security, it is a best practice to separate the HTTP server from the application server.  This can be either on 2 different physical machines, with the HTTP server sitting in a DMZ and the app server sitting behind a firewall, or even on a single machine using firewall rules to block external access to the app server.  This is because there is only so much someone can do if they hack the HTTP server, but if they hack the app server they have access to your database, configuration files (some of which may contain passwords), etc. and can do a lot more damage.

    3) This is a convenient way to run several app servers on a single site without requiring your users to remember convoluted urls or ports.  Using this same method, you could easily run JIRA, Confluence, Subversion, Fisheye, etc. (though I wouldn't suggest putting Crowd out there) through easy urls like www.mysite.com/jira, www.mysite.com/wiki, etc.

    4) Along the same lines, most people want to run publicly available sites on port 80 so users don't have to enter a port in their urls.  With Tomcat on Linux, the only way to do that is to run it as the root user, which is a very very bad idea.

    As for the problems you are having, the first, second, and third things I would check are memory, memory, memory.  Java in production environments is very memory hungry, and will slow to a crawl when choked of enough memory.  First check that your machine has enough physical memory to handle all the stuff running (the whole Atlassian suite of tools requires at least 2GB).  Second, make sure you are giving enough memory to Tomcat - if you have a lot of users and/or issues in your JIRA, you probably need to increase the heap space.  I'm pretty sure how to do this is listed somewhere in the documentation, I remember seeing it in the past.

    Oh, and the reason apps like Drupal can run on Apache directly is because they use PHP for their page generation.  PHP is a scripting language that is quick and easy to learn and use, although not nearly as powerful as Java, and Apache has modules that add native support for it.  However, be aware that running a Drupal site exposes you to the same security concerns I mentioned above, and PHP gets hacked quite frequently.  So even for a Drupal or other PHP site, I would still run it on an internal site on a different port and use mod_proxy or port redirecting to access it, putting a firewall between your publicly available site and the back-end PHP site.

  7. Oct 02, 2010

    Anonymous

    It seems that under Mac OS X Server Snow Leopard, you need to put in the proxyName="jira.example.com" proxyPort="80".

    1. Dec 16, 2010

      Anonymous

      We also had to add that line and are using Windows Server 2003. Apparently it has more to do with the configuration than the environment. Glad you posted that tho, because your comment is where I got the idea to try that.

  8. Dec 02, 2010

    Matt Doar (CustomWare)

    f you're using Apache to terminate an SSL connection and you get the UrlSchemeMismatchException from the Diagnostics class in the log file, then you can add parameters to the Connector element in conf/server.xml to change the uri that JIRA receives in an HttpServletRequest to match whatever you've defined as your base URL.

    For instance with a baseURL of https://jira.example.com add this to the Connector: scheme="https" proxyPort="443"

    1. May 24, 2011

      Anonymous

      Thanks Matt, great work. I've been searching for this solution. I hope it get's promoted somewhere a little more visible.

  9. Jan 21, 2011

    Yogesh Varma

    I guess this documentation is applicable to Standalone installation. Can anyone help me in getting the correct step by step procedure to configure WAR installation with Apache?

  10. Jan 24, 2011

    Shrike

    I'm trying to set up Jira behind Apache and allow bote http and https methods to access. I have my dns "jira.example.com" and I've done the following settings:

    Jira (conf/server.xml):

    Apache:

    Accessing via http works. But accessing via https do not.
    Jira shows warning on homepage: "Dashboard Diagnostics: Mismatched URL Scheme".
    All widgets shows http error "Not Found" as they trying to load content from "http://localhost:81". If I change in appache settings for <VirtualHost *:443> from
    "ProxyPass / http://localhost:81/" to "ProxyPass / http://server_IP:81/" then all widgets just have been loading infinitely.

    What did I miss?

  11. Apr 14, 2011

    Karl Rune Nilsen

    If the apache server is set up with authentication, you need mod_headers to remove the Authorization header before the proxy stage, otherwise Jira will always return a 401 error message.

    Example apache config:

    Remember to load the mod_headers module

  12. Apr 24, 2011

    Anonymous

    Hi,

    I have apache set up for basic authentication for jira . I have now prompted for username/password while accessing https://example.com/jira and was able to login fine. But this does not seem to me logged out when I click on Logout link. I will be logged in automatically without prompting for login (either I click on "relogin" or close the browser and reopen). Is this something to do at JIRA side or apache? Please provide some insight on how to fix this?

    Thanks

  13. May 02, 2011

    Stelian Iancu

    Hello everybody,

    I am trying to setup this on Windows 7 Enterprise and I have a problem at step 1.

    I've changed the server.xml file so that now I have the following:

    I have the Base URL setup to http://localhost:8080/jira. I've restarted the server and when I try to access http://localhost:8080/jira I get a 404. However http://localhost:8080 still works. Any idea what's wrong?

    I don't even have Apache yet installed on the box.

    Thanks,
    Stelian

    1. Aug 23, 2011

      Anonymous

      Hi Stelian,

      Has this problem been solved? If not please open a ticket for us to look at by sending an email to jira-support AT atlassian.com And attach your full server.xml file along with your catalina.out file for us to have a look at.

      Cheers,

      Michael (Atlassian)

  14. Oct 21, 2011

    Anonymous

    Hi,

    I've posted an article about my setup of Atlassian apps integrated with Apache. You can host any number of applications on any number of server instances, proxy-ed not only from relative paths in your domain but from subdomains as well:

    http://dailyjavatips.com/2011/10/23/flexible-tomcat-setup-atlassian-apps/

    I hope you can find this useful for this kind of setups in general, and in particular for hosting the Atlassian apps.

    Cheers,

    Mihai Roman

  15. Jan 15, 2012

    Anonymous

    (sad) no information about IP address JRA-22399 with JIRA 5.0 (sad)

  16. Feb 07, 2012

    Anonymous

    Hi ,

    I am stuck on step 2 . how to configure httpd ?? i use windows and i am not able to find mod proxy in my JIRA installation , cant even find apache-site.conf .

    i am using a JIRA on inbuilt tomcat... plz help