Integrating Bitbucket Server with Apache HTTP Server

About using Apache software

This section has general information pertaining to the use of Apache HTTP Server and Apache Tomcat. It is important that you read this section before proceeding to the steps that follow.

Configuring Tomcat 7

The Bitbucket Server distribution includes an instance of Tomcat 7, the configuration of which is determined by the contents of the  <Bitbucket home directory>/shared/server.xml  file. Note that any changes that you make to the server.xml file will only be effective upon starting or re-starting Bitbucket Server.

You may find it helpful to refer to the Apache Tomcat 7.0 Proxy Support HowTo page.

Configuring Apache HTTP Server

You may find it helpful to refer to the Apache HTTP Server Documentation, which describes how you can control Apache HTTP Server by changing the contents of the httpd.conf file. The section on Apache Module mod_proxy is particularly relevant. Note that any changes you make to the httpd.conf file will only be effective upon starting or re-starting Apache HTTP Server.

Step 1: Configure the Tomcat Connector

Find the normal (non-SSL) Connector directive in Tomcat's  <Bitbucket home directory>/shared/server.xml  file, and add the scheme,  proxyName, and proxyPort attributes as shown below. Instead of mycompany.com, set the proxyName attribute to your domain name that Apache HTTP Server will be configured to serve. This informs Bitbucket Server of the domain name and port of the requests that reach it via Apache HTTP Server, and is important to the correct operation of the Bitbucket Server functions that construct URLs.

<Connector port="7990" 
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    useBodyEncodingForURI="true"
    redirectPort="8443"
    compression="on"
    compressableMimeType="text/html,text/xml,text/plain,text/css,application/json,application/javascript,application/x-javascript"
    scheme="http"
    proxyName="mycompany.com" 
    proxyPort="80" />

Note: Apache HTTP Server's ProxyPreserveHost directive is another way to have the hostname of the incoming request recognised by Bitbucket Server instead of the hostname at which Bitbucket Server is actually running. However, the ProxyPreserveHost directive does not cause the scheme to be properly set. Since we have to mess with Tomcat's Connector directive anyway, we recommend that you stick with the above-described approach, and don't bother to set the ProxyPreserveHost in Apache HTTP Server.

For more information about configuring the Tomcat Connector, refer to the Apache Tomcat 7.0 HTTP Connector Reference.

Step 2: Change Bitbucket Server's base URL

After re-starting Bitbucket Server, open a browser window and log into Bitbucket Server using an administrator account. Go to the Bitbucket Server administration area and click Server settings (under 'Settings'), and change Base URL to match the proxy URL (the URL that Apache HTTP Server will be serving).

Step 3 (optional): Set a context path for Bitbucket Server

By default, Bitbucket Server is configured to run with an empty context path; in other words, from the 'root' of the server's name space. In that default configuration, Bitbucket Server is accessed at:

http://localhost:7990/

It's perfectly fine to run Bitbucket Server with the empty context path as above. Alternatively, you can set a context path by changing the Context directive in Tomcat's  <Bitbucket home directory>/shared/server.xml  file:

<Context path="/bitbucket" docBase="${catalina.home}/atlassian-bitbucket" reloadable="false" useHttpOnly="true">
    ....
</Context>

If you do set a context path, it is important that the same path be used in Step 5, when setting up the ProxyPass and ProxyPassReverse directives. You should also append the context path to Bitbucket Server's base URL (see Step 2).

Step 4: Enable mod_proxy and mod_proxy_http in Apache HTTP Server

In the mod_proxy documentation, you will read that mod_proxy can be used as a forward proxy, or as a reverse proxy (gateway); you want the latter. Where the mod_proxy documentation mentions 'origin server', it refers to your Bitbucket Server instance. Unless you have a good reason for doing otherwise, load mod_proxy and mod_proxy_http dynamically, using the LoadModule directive; that means un-commenting the following lines in the httpd.conf file:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Experienced administrators may be aware of the Apache Connector module, mod_jk. Atlassian does not recommend use of the mod_jk module with Bitbucket Server, since it has proven itself to be less reliable than mod_proxy.

Step 5: Configure mod_proxy to map requests to Bitbucket Server

To configure mod_proxy for use with Bitbucket Server, you need to use the ProxyPass and ProxyPassReverse directives in Apache HTTP Server's httpd.conf file as follows:

ProxyPass        / http://localhost:7990/ connectiontimeout=5 timeout=300
ProxyPassReverse / http://localhost:7990/

Suppose Apache HTTP Server is configured to serve the mycompany.com domain; then the above directives tell Apache HTTP Server to forward web requests of the form http://mycompany.com/* to the Tomcat connector (Bitbucket Server) running on port 7990 on the same machine.

The connectiontimeout attribute specifies the number of seconds Apache HTTP Server waits for the creation of a connection to Bitbucket Server.

The timeout attribute specifies the number of seconds Apache HTTP Server waits for data to be sent to Bitbucket Server.

If you set up a context path for Bitbucket Server in Step 3, you'll need to use that context path in your ProxyPass and ProxyPassReverse directives. Suppose your context path is set to "/bitbucket", the directives would be as follows:

ProxyPass        /bitbucket http://localhost:7990/bitbucket connectiontimeout=5 timeout=300
ProxyPassReverse /bitbucket http://localhost:7990/bitbucket

If Bitbucket Server is to run on a different domain and/or different port, you should use that domain and/or port number in the ProxyPass and ProxyPassReverse directives; for example, suppose that Bitbucket Server will run on port 9900 on private.mycompany.com under the context path /bitbucket, then you would use the following directives:

ProxyPass        /bitbucket http://private.mycompany.com:9900/bitbucket connectiontimeout=5 timeout=300
ProxyPassReverse /bitbucket http://private.mycompany.com:9900/bitbucket

Step 6: Configure mod_proxy to disable forward proxying

If you are using Apache HTTP Server as a reverse proxy only, and not as a forward proxy server, you should turn forward proxying off by including a ProxyRequests directive in the httpd.conf file, as follows:

ProxyRequests Off

Step 7: Allow proxying to Bitbucket Server from everywhere

Strictly speaking, this step is unnecessary because access to proxied resources is unrestricted by default. Nevertheless, we explicitly allow access to Bitbucket Server from any host so that this policy will be applied regardless of any subsequent changes to access controls at the global level. Use the Proxy directive in the httpd.conf file as follows:

<Proxy *>
    Order Deny,Allow
    Allow from all
</Proxy>

The Proxy directive provides a context for the directives that are contained within its delimiting tags. In this case, we specify a wild-card url (the asterisk), which applies the two contained directives to all proxied requests.

The Order directive controls the order in which any Allow and Deny directives are applied. In the above configuration, we specify "Deny,Allow", which tells Apache HTTP Server to apply any Deny directives first, and if any match, the request is denied unless it also matches an Allow directive. In fact, "Deny,Allow" is the default; we include it merely for the sake of clarity. Note that we specify one Allow directive, which is described below, and don't specify any Deny directives.

The Allow directive, in this context, controls which hosts can access Bitbucket Server via Apache HTTP Server. Here, we specify that all hosts are allowed access to Bitbucket Server.

Step 8 (optional): Configure Apache HTTP Server for SSL

If you want to set up SSL access to Bitbucket Server, follow the instructions on Securing Bitbucket Server with Apache using SSL. When you are finished, users will be able to make secure connections to Apache HTTP Server; connections between Apache HTTP Server and Bitbucket Server will remain unsecured (not using SSL). If you don't want to set up SSL access, you can skip this section entirely.

Note: It would be possible to set up an SSL connection between Apache HTTP Server and Tomcat (Bitbucket Server), but that configuration is very unusual, and not recommended in most circumstances.

A note about application links

When an application link is established between Bitbucket Server and another Atlassian product (for example JIRA), and Bitbucket Server is operating behind Apache HTTP Server, the link from the other product to Bitbucket Server must be via the proxy URL; that is, the 'reciprocal URL' from, say JIRA, to Bitbucket Server must match the proxy name and port that you set at Step 1.

Troubleshooting

In general, if you are having problems:

• 1. Ensure that Bitbucket Server works as expected when running directly from Tomcat on http://localhost:7990/bitbucket.
  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 Bitbucket Server Knowledge Base.

In particular:

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