Reverse Proxy and Application Link Troubleshooting Guide
What is a reverse proxy?
A reverse proxy sits in front of an application and directs incoming traffic to it. The most common reverse proxies are Apache, IIS, and Nginx.
Reverse proxies are used to:
- Provide an easy to remember URL without a port number (that is, port forwarding), such as
- Provide SSL encryption for the application; that is SSL terminates at the proxy, and communication between the proxy and the application is unsecured.
- Provide firewall, load-balancing, caching and other services.
Reverse proxies generally come in two flavors:
HTTP proxies communicate over HTTP with the application server. Common types of HTTP proxies are:
- Apache, using
- IIS, using Application Request Routing (ARR)
The Apache JServ Protocol (AJP) is a binary protocol for communicating with an Apache Tomcat server. It provides greater integration between the application server and the reverse proxy. Common types of AJP proxies are:
- Apache, using
- IIS, using AJP ISAPI extension
Which should you use in your environment?
Atlassian recommends the use of an HTTP proxy - they're easier to configure, and you can choose the front end you want to use.
Benefits of an HTTP proxy:
- Use any web server technology
- Minimal configuration required
Benefits of an AJP proxy:
- Tighter integration with Apache Tomcat - support for load balancing, proxy awareness
- More granular logging capabilities
Configuring Tomcat for use with an HTTP proxy
As of Bitbucket Server 5.0, you can't configure any Tomcat connectors directly.
server.xml configurations have been replaced by
<Bitbucket home directory>
Please read through Migrate server.xml customizations to bitbucket.properties
When using a reverse proxy, the application server (Tomcat) must be aware of the proxy to ensure that the correct addresses and URLs are sent back to the client. If this is not correctly set up, Tomcat will return the hostname and IP that it's listening on, rather than the address that clients use to access the application.
The most reliable way to configure your HTTP connector is to include the proxy information:
<Connector port="8080" connectionTimeout="20000" maxThreads="200" minSpareThreads="10" enableLookups="false" acceptCount="10" URIEncoding="UTF-8" proxyName="atlassian.com" proxyPort="443" scheme="https" secure="true" />
The necessary attributes are
proxyPort , and
scheme . Replace the values above with values suitable for your deployment.
Set this attribute to true if you wish to have calls to request.isSecure() to return true for requests received by this Connector. You would want this on an SSL Connector or a non SSL connector that is receiving data from a SSL accelerator, like a crypto card, a SSL appliance or even a webserver. The default value is false.
For more information on these attributes, please see the.
It is possible to provide the correct headers to the application server by using
ProxyPreserveHost (or the equivalent for your reverse proxy). Making the modifications to the connector ensures that the application server responds correctly, regardless of the reverse proxy type or configuration.
Configuring Tomcat for use with an AJP proxy
As of Bitbucket Server 5.0, it is not possible to configure AJP between your proxy and Tomcat server.
Because the AJP protocol is a binary protocol that offers tighter integration with Apache Tomcat, most problems with AJP are caused by the configuration of the proxy server. The only modification to the application server is an AJP connector:
<Connector port="8009" protocol="AJP/1.3" />
Problems caused by incorrect proxy configuration
Unable to retrieve response
One application was not able to obtain the response from the other application. Examine the exception type for further context
Typically, this is caused by content being encoded twice - once by the application, and then again by the reverse proxy. By default, Atlassian Applications have GZIP compression enabled.
Disable GZIP compression at the reverse proxy, or via the application configuration. E.g.
- Compressing an HTTP Response within Confluence
- Enabling GZIP compression - Bamboo
- Configuring Jira application options
Check your proxy configuration
Once your application server is configured correctly, it's important to ensure that your reverse proxy has been configured correctly. We recommend using the minimal configuration to ensure the reverse proxy works correctly before adding additional features such as load balancing and SSL. Refer to Proxying Atlassian Server Applications for more information.