Integrating JIRA with Apache
This page describes how to integrate Apache HTTP Server (also referred to as httpd) with JIRA, utilising mod_proxy so that Apache operates as a reverse-proxy over HTTP. If HTTPS configuration is required, please see our Integrating JIRA with Apache using SSL documentation. Configuring Apache allows for running JIRA on non-standard HTTP port (such as 8080) and users will be able to access JIRA over standard HTTP as their traffic will be routed through the proxy.
Apache can be configured to allow access to JIRA in any of the following methods:
- Directly on its own domain: http://jira.com
- As a subdomain of another domain: http://jira.atlassian.com
- It can also be accessed on a context path on either a domain or subdomain: http://atlassian.com/jira
This documentation will cover a straightforward implementation of mod_proxy using the above three configurations. If a more complication solution is required, refer to the Apache HTTP Server Version Documentation, consult with the Apache SME within your organisation and if need be raise a question on Atlassian Answers or look at getting in touch with one of our Atlassian Experts.
On this page:
Step 1: Configure Tomcat
- Stop JIRA.
Edit Tomcat's
server.xmlto include the required JIRA context path. The below example usespath="/jira"- this means JIRA is accessible onhttp://jiraserver:8080/jiragiven the default JIRA port is used.
Ensure the pathvalue is set with a prepending forward slash (/) . For example,path="/jira"rather thanpath="jira".Edit Tomcat's
server.xmlto include a separate connector to proxy the requests. This requires theproxyName&proxyPortattributes. Replace them with the appropriate domain and port of the proxy, as in the below example:
The proxyNameparameter should be set to the FQDN that the JIRA server will be accessed on - for examplejira.example.comif accessing it on http://jira.example.com orexample.comif accessing it on http://www.example.com/jira. It should not include the context path.- Start JIRA.
- Test that JIRA is accessible on the normal connector, using a context path if applicable - for example
http://jiraserver:8081/jira. - Test that the new connector is working by accessing JIRA on the appropriate proxy connector, for example
http://jiraserver:8080/. This should redirect to the proxy FQDN (in this example, http://jira.atlassian.com), which will fail as the proxy is not yet configured. The test is to ensure Tomcat is set up to correctly redirect to the proxy.
Step 2: Configure Apache HTTP Server
The installation of Apache and configuration of a DNS is not covered in this documentation. Additionally, it is assumed that Apache 2.2 has been installed and DNS entries have been configured for the JIRA domain. As Apache's configuration is specific to the operation system that is used, only some distributions and their configurations are currently documented.
2.1 Enable the Proxy Modules
Debian/Ubuntu
Windows/Other OS
2.2. Configure Apache to use those Modules
Debian/Ubuntu
Windows/Other OS
Step 3: Configure JIRA
- Set Use gzip compression to OFF as in Configuring JIRA Options. GZIP compression is known to cause performance issues using a reverse-proxy, especially if the proxy is also compressing the traffic.
- Set the Base URL to be the FQDN that JIRA will be accessed on, for example http://jira.atlassian.com. This is also located in Configuring JIRA Options.
JIRA can only be configured to respond to a single URL and the Base URL (as in Configuring JIRA Options) must match the URL end-users are accessing. Misconfiguration of this may cause significant problems within JIRA such as the Activity Stream and Dashboard Gadgets failing to function correctly. - Test by accessing JIRA on the FQDN (e.g.: http://jira.atlassian.com), ensuring that JIRA is accessible and all dashboard gadgets correctly display.
Troubleshooting
Hijacked Sessions
Some users have reported problems with user sessions being hijacked when the mod_cache module is enabled. If these problems are encountered, try disabling the mod_cache module.
This module is enabled by default in some Apache HTTP Server version 2 distributions.
Permission Denied Errors enabling mod_proxy (and mod_jk) on Linux distros that use SELinux
Users have reported 'permission denied' errors when trying to get mod_proxy (and mod_jk) working. See How to debug SELinux for information on how to debug SELinux.
Running Mac OS X
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, as below.
Additionally we do not recommend using Max OS X as it is not supported, as in our Supported Platforms.
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
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.
Too many redirects
Both Tomcat & Apache are redirecting, when only one should be. Disable redirection in Tomcat (revert any changes as in Running JIRA over SSL or HTTPS) and check that there is only one redirection in Apache.
General Problems
- Clear the browser cache and try again.
- Ensure that JIRA works as expected when running directly from Tomcat and bypassing Apache. For example, accessing
http://jiraserver:8080instead of http://jira.atlassian.com. - Increase the LogLevel for Apache to debug and restart it.
- Attempt to access JIRA and check the Apache Log Files for any errors.
- Raise a question on Atlassian Answers for assistance.
403 Forbidden error
Add the RequestHeader unset Authorization line to the apache configuration page to disable authorization headers.
See Also
- Integrating JIRA with Apache using SSL
- Configuring Apache Reverse Proxy Using the AJP Protocol
- For more advanced
mod_webappconfigurations (eg. SSL), see this mod_proxy guide. - Apache Virtual Host documentation
Was this helpful?
Thanks for your feedback!
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.
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.
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.
Anonymous
THANK YOU VERY MUCH! I've lost hours to resolve an "JIRA reports ..." issue just because I didn't know about "scheme" attribute! Guys from Atlassian: you've developed great product, but you should improve your documentation. I've spend almost 10 days deploying JIRA, Confluence and Crowd. (FishEye and other interesting plugins are waiting
)
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
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:Note that the requested path that Apache sees,
/private/jiramatches 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.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
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?
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.
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
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.
Anonymous
It seems that under Mac OS X Server Snow Leopard, you need to put in the proxyName="jira.example.com" proxyPort="80".
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.
Matt Doar (ServiceRocket)
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"
Anonymous
Thanks Matt, great work. I've been searching for this solution. I hope it get's promoted somewhere a little more visible.
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?
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?
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
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
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
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)
Anonymous
Hey Stelian,
I had the same issue as you and wanted to post a resolution for others.
Instead of:
<ContextdocBase="${catalina.home}/atlassian-jira"path="/jira"reloadable="false"useHttpOnly="true"><ContextdocBase="${catalina.home}/confluence"path="/jira"reloadable="false"useHttpOnly="true">Thanks
Billy
Anonymous
Just spent an hour on this also.
My problem was there was another reference to path=" " that I did not remove and simply added in path"/jira". So I assume with two path declared, it got confused. Removed the earlier one and it works now
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
Anonymous
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
Anonymous
Have you found a solution to this?
Can someone pleeeeaaaasssseeee adjust this for windows users please.
Anonymous
To fellow Anonymous users - It may help to understand that Apache and Tomcat are two different things, and Apache is not apart of the JIRA installation (while Tomcat is).
Apache is an HTTP Server, serving HTTP. Tomcat is a Servlet and JSP Server serving Java technologies (like JIRA).
This article assumes that you have both JIRA (bundled with Tomcat) and Apache installed already on your system. Windows users new to Apache may want to familiarize themselves with the Windows installation/documentation prior to completing the integration effort with JIRA. A good place to start is here: http://wiki.apache.org/httpd/FAQ, and also taking a look at the official Apache documentation: http://httpd.apache.org/docs/2.4/.
Anonymous
Hi ,
I am stuck on step 2 . how to configure httpd using windows 7?
Naeem Malik
Step 2 for window 7 users:
Uncomment various LoadModule directives
Write down the following code anywhere after LoadModule directives
JIRA should now be integrated with 'httpd'. Restart the Apache Server and you should be able to view JIRA at
http://localhost/jira(i.e. on port 80).Anonymous
As I understand setting something like:
Anonymous
Thanks Naeem,
This worked for me on Windows Server® 2008 R2
Darren
Anonymous
Naeem,
Not sure if you managed this yourself..
But did you manage to setup Confluence on that same setup?
I have both.. Obviously no matter if I try load confluence JIRA loads instead.
Seems I may need to use a different module to this/// . (
<IfModule mod_proxy.c>?Thanks
Darren
Sylnsr
To get this working under https, I had to not do the "
a2ensite jira-mod_proxy" step. What I experienced was that when I redirect from http to https, it would work for everything I needed it to except Confluence/Jira.Once I ran a2dissite to disable the jira-mod_proxy config, everything started working correctly.
This documentation is so jacked!
Anonymous
I may be just displaying my own incompetence here, but I initially failed to set the JIRA Base URL, since that wasn't specified as a last step.
I see now that there is a warning about that at the top of the page about doing that, but I think, perhaps, an explicit step in the instructions could be a good idea.
Anonymous
Actually there is a typo serious one ... I lost half a day just on this ....
pathvalue is set without a prepending forward slash (/) . For example,path="jira"rather thanpath="/jira".I just tried to reverse and that was the ONLY issue I was having it needed the path="/jira" !!! Nots sure why
David Currie [Atlassian]
Hey, thanks for letting us know about this - I've updated the page accordingly after verifying that configuration. Sorry that it caused you to waste half a day configuring it.
Anonymous
We running JIRA on Tomcat with Apache behind a network proxy. We need to connect to an external svn repository through this proxy. But I don't find the right config.
I've already tried following in tomcat settings:
Both doesn't work. Does anyone know the correct configuration?
David Currie [Atlassian]
Hey, from the looks of your comment, you're looking to configure an outbound (or forwarding) proxy for JIRA. These docs are for Apache to act as a reverse-proxy, please take a look at our How to Configure an Outbound HTTP and HTTPS Proxy for JIRA applications KB for information on how to configure an outbound proxy.
Darren Pegg
Hi All,
At the moment my JIRA/Confluence are accessible via either the ip/servername and port number.
I want to anable users to access either JIRA and Confluence via http//:jira.domain.co.uk
This is for internal users only, same setup as intranet would be. I will not publishing this on www.
JIRA:8080 and Confluence:8090 are installed on the same VM within a DMZ.
I have installed apache2.2 and created what i think was the correct DNS entry.
Though I cannot get it to work. I have tried numerous tutorials, and I simply feeling like tearing my hair out.
Does anyone know of a definitive how to guide?
Many thanks
Darren
Darren Pegg
Hi All,
WIndows Server 2008 R2 - Running both JIRA and Confluence on a VM (vSphere)
Managed this eventually with the following config: Apache 2.2
within the .httpd
Adding the following modules:
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
Then by adding the following in the vhost section.
<IfModule mod_proxy.c>
<Proxy *>
Order deny,allow
Allow from all
</Proxy>
</IfModule>
NameVirtualHost jira.domain.co.uk:80
<VirtualHost jira.domain.co.uk:80>
ProxyPreserveHost On
ProxyRequests off
ServerName jira.domain.co.uk
ServerAlias jira
ProxyPass / http://localhost:8080/
ProxyPassReverse / http://localhost:8080/
</VirtualHost>
NameVirtualHost confluence.domain.co.uk:80
<VirtualHost confluence.domain.co.uk:80>
ProxyPreserveHost On
ProxyRequests off
ServerName confluence.domain.co.uk
ServerAlias confluence
ProxyPass / http://localhost:8090/
ProxyPassReverse / http://localhost:8090/
</VirtualHost>
Changed the base urls for both Confluence and JIRA. I also didnt need to use a context path for either within the server.xml, after a reboot the avatars and gadgets ect worked as normal.
Regards
Darren
Robert Stoffers
Having trouble on RHEL 6.x and pulling your hair out? Try this:
-A RH-Firewall-1-INPUT -m tcp -p tcp dport 80 -j ACCEPT
-A RH-Firewall-1-INPUT -m tcp -p tcp sport 80 -j ACCEPT
tao sun
I am configuring a typical "Apache + HTTPS + (JIRA, Fisheye, Confluence)" model. If user uses https://jira" to access JIRA, My questions are:
Jason Smart
It doesn't look like OS X (10.9 Mavericks) is still using webperfcache. I tried
man webperfcacheon my Mavericks system, and there is no man entry. The link in this article to the Apple developer man pages also turns up no results for webperfcache. I have just configured a reverse proxy on OS X by modifying the configuration files used by the Server.app and could find no reference to webperfcache. My setup is also working fine.Ilya Suzdalnitski
After fighting with this setup for 10 hrs straight, I figured out that in a local network the proxyName parameter of server.xml configuration file has to be set to the ip address of the server, e.g. 192.168.0.108
In my case the Apache's ProxyPass goes like this:
ProxyPass /jira http://localhost:8080/jira
To make others' lives easier, the server.xml file is located in /opt/atlassian/jira/conf
David Currie [Atlassian]
Hey Ilya Suzdalnitski the
proxyNameparameter should be set to the FQDN that the JIRA server will be accessed on - for examplejira.example.comif accessing it on http://jira.example.com orexample.comif accessing it on http://www.example.com/jira.Ilya Suzdalnitski
Thanks for your reply!
If I don't have a domain name pointing to my server, I would have to configure a local DNS server that would forward the requests made to example.com to my local server's IP (i.e. 192.168.0.108)?
Nikhil Bhatnagar
Dear members,
I have a weird issue [weird as I cant find a solution
I have integrated JIRA with apache. It works fine for browsing but has an issue - I am not able to release/unrelease a version. I am not able to add users to a group. It just hangs. Probably it cant connect to database through apache port? But then its able to fetch the username as i type first few letters. When i change the port to Tomcat, it works. I am using IE 9
Any pointers?
Angel Cox
We ran into a strange issue where client was denied by the server, didn't matter if the proxy was http or ajp and proxy was configured to allow all both in the vhost and the proxy_http.conf. After alot of digging support had me reinstall apache, however the issue returned after I performed our security configurations. Our issue was due to use of mod_evasive in apache to prevent against ddos attempts. Disabled the mod_evasive module and the forbidden errors cleared like a champ. Original issue I could find of this is linked. Apache Mail Archive