Configure Jira to run behind a NGINX reverse proxy

Still need help?

The Atlassian Community is here for you.

Ask the community


Atlassian applications allow the use of reverse-proxies within our products, however Atlassian Support does not provide assistance for configuring them. Consequently, Atlassian can not guarantee providing any support for them.

If assistance with configuration is required, please raise a question on Atlassian Community.

Platform notice: Server and Data Center only. This article only applies to Atlassian products on the Server and Data Center platforms.

Support for Server* products ended on February 15th 2024. If you are running a Server product, you can visit the Atlassian Server end of support announcement to review your migration options.

*Except Fisheye and Crucible

Purpose

This page describes a possible way to use Nginx to proxy requests for Jira running in a standard Tomcat container. You can find additional documentation that explains how to use Apache mod_proxy for the very same purpose.

Solution

In this example, we want a setup where Jira can be accessed at the address http://www.atlassian.com/jira (on standard HTTP port 80), while Jira itself listens on port 8080 with context path /jira.

Set the Context Path

If you want Jira to serve on http://jira.atlassian.com skip this section.


  1. Set your Jira application path (the part after hostname and port). To do this in Tomcat (bundled with Jira), edit <Jira-Install>/conf/server.xml, locate the "Context" definition: 

    <Context docBase="${catalina.home}/atlassian-jira" path="" reloadable="false" useHttpOnly="true">
  2. Change the path to the below:

    <Context docBase="${catalina.home}/atlassian-jira" path="/jira" reloadable="false" useHttpOnly="true">
  3. Restart Jira and verify it can be accessed on the base URL (for example http://www.atlassian.com/jira). You may receive some errors about the dashboard being incorrectly configured - we'll fix this in the next section.

Configure the Connector

  1. Configure the HTTP connectors so we have one serving as a proxy connector and another for troubleshooting. This is done in the same <Jira-Install>/conf/server.xml file, locate this code segment:

    <Connector port="8080"
      relaxedPathChars="[]|" 
      relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;" 
      maxThreads="150" 
      minSpareThreads="25" 
      connectionTimeout="20000" 
      enableLookups="false" 
      maxHttpHeaderSize="8192" 
      protocol="HTTP/1.1" 
      useBodyEncodingForURI="true" 
      redirectPort="8443" 
      acceptCount="100" 
      disableUploadTimeout="true"/>
  2. And add the proxyName and proxyPort elements (replacing them with the appropriate properties), and another connector below - this is used for troubleshooting to bypass the proxy:

    <!-- Nginx Proxy Connector without https scheme -->
    <Connector port="8080"
      relaxedPathChars="[]|" 
      relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"  
      maxThreads="150" 
      minSpareThreads="25" 
      connectionTimeout="20000" 
      enableLookups="false" 
      maxHttpHeaderSize="8192" 
      protocol="HTTP/1.1" 
      useBodyEncodingForURI="true" 
      redirectPort="8443" 
      acceptCount="100" 
      disableUploadTimeout="true"
      proxyName="www.atlassian.com" 
      proxyPort="80"/> 
     
    <!-- OPTIONAL,Nginx Proxy Connector with https scheme-->
    <Connector port="8081"
      relaxedPathChars="[]|" 
      relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"  
      maxThreads="150" 
      minSpareThreads="25" 
      connectionTimeout="20000" 
      enableLookups="false" 
      maxHttpHeaderSize="8192" 
      protocol="HTTP/1.1" 
      useBodyEncodingForURI="true" 
      redirectPort="8443" 
      acceptCount="100" 
      disableUploadTimeout="true"
      proxyName="www.atlassian.com" 
      proxyPort="443" 
      scheme="https" 
      secure="true"/> 
     
    <!-- Standard HTTP Connector without any proxy config -->
    <Connector port="8082"
      relaxedPathChars="[]|" 
      relaxedQueryChars="[]|{}^&#x5c;&#x60;&quot;&lt;&gt;"  
      maxThreads="150" 
      minSpareThreads="25" 
      connectionTimeout="20000" 
      enableLookups="false" 
      maxHttpHeaderSize="8192" 
      protocol="HTTP/1.1" 
      useBodyEncodingForURI="true" 
      redirectPort="8443" 
      acceptCount="100" 
      disableUploadTimeout="true"/>

Configure Nginx

  1. Update the Nginx settings to have the below server (replacing www.atlassian.com with the FQDN and jira-hostname with the hostname of the server):

    server {
        listen www.atlassian.com:80;
        server_name www.atlassian.com;
        location /jira {
            proxy_set_header X-Forwarded-Host $host;
            proxy_set_header X-Forwarded-Server $host;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; 
            proxy_pass http://jira-hostname:8080/jira;
            client_max_body_size 10M;
        }
    }

    Please don't forget to change client_max_body_size value accordingly to your own application needs. 

    By default Nginx allows 1MB file to be attached into Jira. So, parameter client_max_body_size is necessary to set the maximum size of attachment that can be uploaded into Jira. 

    A more complex nginx config for SSL connection is below, note the <variables> have to be configured specifically for your system:

    server {
    	listen <ip_address>:443 ssl;
    
    	server_name <jira_base_fqdn>;
    	
    
    	ssl_certificate             /usr/local/psa/var/certificates/scfBrNudT;
    	ssl_certificate_key         /usr/local/psa/var/certificates/scfBrNudT;
    
    	client_max_body_size 134217728;
    
    	access_log "/var/www/vhosts/system/_.technios.com/logs/proxy_access_ssl_log";
    	error_log "/var/www/vhosts/system/_.technios.com/logs/proxy_error_log";
    
    	root "<local_httpdocs>";
    
    	#extension letsencrypt begin
    	location ^~ /.well-known/acme-challenge/ {
    		root <local_htdocs>;
    
    		types { }
    		default_type text/plain;
    
    		satisfy any;
    		auth_basic off;
    		allow all;
    
    		location ~ ^/\.well-known/acme-challenge.*/\. {
    			deny all;
    		}
    	}
    	#extension letsencrypt end
    
    	#extension sslit begin
    
    	#extension sslit end
    
    	location / {
    		proxy_pass https://<ip_address>:<local_proxy_port>;
    		proxy_hide_header upgrade;
    		proxy_set_header Host             $host;
    		proxy_set_header X-Real-IP        $remote_addr;
    		proxy_set_header X-Forwarded-For  $proxy_add_x_forwarded_for;
    		access_log off;
    
    	}
    
    
    
    	proxy_connect_timeout 180s;
    proxy_send_timeout 180s;
    proxy_read_timeout 180s;
    fastcgi_send_timeout 180s;
    fastcgi_read_timeout 180s;
    }


  1. If configuring SSL, follow the instructions in https://mozilla.github.io/server-side-tls/ssl-config-generator/ to generate the profile.
  2. If you want to redirect HTTP to HTTPS the below can be used instead of the above block (remember to replace www.atlassian.com with the FQDN):

    server {
            listen  80 default_server;
            listen  [::]:80 default_server ipv6only=on;
            server_name atlassian.com www.atlassian.com;
            return  301 https://$server_name$request_uri;
    }
  3. Due to Page out of date error thrown when modifying Application Access page in Jira server , ensure that native gzip compression is turned on in Jira. This will override Nginx's gzip compression, if configured, with no adverse effects.
  4. Restart Nginx.

Test Jira

  1. Restart Jira and verify it can be accessed on the base URL (for example http://www.atlassian.com/jira) and also the 8081 port (e.g.: http://www.atlassian.com:8080/jira).
  2. For the normal operation of Jira, you will also need to set the base URL accordingly. In this example, the base URL shall be set to http://www.atlassian.com/jira.

Notes

  • For the settings above to take effect, you need to restart both Jira and Nginx.
  • If you encounter problems creating triggers when linked to Stash, please see the resolution described in the Unable to create Stash trigger in JIRA when using Nginx article.

    If you are facing loading problem with a page in Jira, you will need to increase proxy_buffer_size to 8k. The default value for proxy_buffer_size is set to the page size of your system which on an x86/x86_64 is 4k.

    If you encounter problems with input validation, it might be caused by the gzip compression enabled in reverse proxying. Such issue is described in the Creating a Confluence Gadget in JIRA Fails article.




DescriptionThis page describes a possible way to use Nginx to proxy requests for JIRA running in a standard Tomcat container. You can find additional documentation that explains how to use Apache mod_proxy for the very same purpose
ProductJira
PlatformServer
Last modified on Apr 16, 2024

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.