Proxying Atlassian server applications with Microsoft Internet Information Services (IIS)

This page explains how to establish a network topology in which Internet Information Services (IIS) acts as a reverse proxy for Atlassian server applications. The page has been written as a recipe for success – we recommend you follow it step by step. 

 You might consider using a reverse proxy when you want users to access the Atlassian applications: 

• at their own domains, such as   http://our<atlassianapp>.com/
• at subdomains of another domain, such as  http://my<atlassianapp>.example.com/
• at context paths on either a domain or subdomain, such as   http://example.com/my<atlassianapp>
• on different HTTP ports, such as 9800, 9850, etc.

For more complex scenarios, you can refer to the Microsoft IIS Documentation, consult with an Internet Information Services (IIS) specialist in your organisation, ask the Atlassian Community, or contact an Atlassian Partner.

The instructions on this page apply to the following Atlassian server applications:

• JIRA server applications (JIRA Software Server, JIRA Core, JIRA Service Desk)
• Confluence Server
• Bamboo Server
• Bitbucket Server
• Fisheye
• Crucible
• Crowd

In the examples that follow on this page, <atlassianapp> refers to the name of any of the Atlassian server applications above.

Atlassian server applications bundle a web server, which allows them to run without needing a proxy server. For most Atlassian applications, the bundled web server is Apache Tomcat (Fisheye and Crucible use Jetty). Consequently, you need to configure both Tomcat (or Jetty if using Fisheye or Crucible) and IIS when proxying an Atlassian application.

Prerequisites

You'll need the following:

Internet Information Services (IIS) version 7.0, 8.0 or 10.0 installed

You may find it helpful to refer to the Microsoft IIS Documentation to install IIS in your Microsoft Windows Server. (http://www.iis.net/learn/get-started/whats-new-in-iis-8/installing-iis-8-on-windows-server-2012)

DNS entries in place and configured for your domains

You should check, perhaps with your system or network administrator, whether the current DNS configuration for your organization will need changes to support the proxy topology you wish to set up.

The Atlassian applications installed, and accessible through a web browser

Install the Atlassian applications in the usual way.

Part A. Configure the Atlassian applications

This section describes how to configure the Tomcat (or Jetty) web server bundled with each Atlassian application to run behind a reverse proxy.

1. Stop the Atlassian applications

Stopping the application also stops Tomcat.

In Windows, Atlassian applications are typically stopped/started using scripts in the "bin" directory where you installed the product. Alternatively, you may have setup the application to run as a Windows Service.

See the documentation for your product for instructions:

• Jira
• Confluence
  
• Bamboo
  
• Bitbucket
  
• Crucible
• Crowd 

2. Set the context path

Fisheye and Crucible

If you're proxying Fisheye or Crucible, configure the web context path for Jetty from the admin area. See Configuring the Fisheye web server.

Once you've done that, continue with Part B below.

Bitbucket Server 5.0+

In Bitbucket Server 5.0+, the context path can be changed by modifying server.context-path in $BITBUCKET_HOME/shared/bitbucket.properties

server.context-path=/bitbucket

JIRA applications, Confluence, Bitbucket Server 4.x and below, Bamboo

If you're proxying any of these Atlassian server applications, configure the context path in the Tomcat server.xml file as follows.

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

In the Tomcat server.xml configuration file for all applications except Crowd, locate the Context directive that looks like this:

Change the directive to add the new context path:

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

Use your own value for <contextpath>. Typically, each application would use a different context path.

It is important that the path value has a leading forward slash (/) like path="/<contextpath>" rather than path="<contextpath>".

Use these instructions to update the Crowd context path.

3. Configure the Connector directive

3.1. Configure Fisheye/Crucible web server (Jetty)

If you're using Fisheye or Crucible, configure the proxy host, proxy scheme and the proxy port from the Admin area. See Configuring the Fisheye web server.

It is possible to change the configuration also directly in the config.xml by having a configuration similar to:

<web-server site-url="http://<subdomain>.<domain>.com" context="">
   <http bind=":8060" proxy-port="80" proxy-scheme="http" proxy-host="<subdomain>.<domain>.com"/> 
</web-server>

3.2. Configure other Atlassian applications web server (Tomcat)

If you're using any of the other Atlassian server applications, configure the Connector directive as follows.

For each application, find the normal (non-SSL) Connector directive in the Tomcat server.xml file, and add the scheme,  proxyName, and proxyPort attributes inside the Connector directive, as below. Use the default values for the other attributes, including for  port , unless you have a particular reason to change them, and use your own domain name for the proxyName value:

<Connector port=<default>
	maxThreads=<default>
    minSpareThreads=<default>
    connectionTimeout=<default>
    enableLookups=<default>
    maxHttpHeaderSize=<default>
    protocol=<default>
    useBodyEncodingForURI=<default>
    redirectPort=<default>
    acceptCount=<default>
    disableUploadTimeout=<default>
	proxyName="<subdomain>.<domain>.com"
	proxyPort="80"
	scheme="http"/>

Note that the proxyName parameter should be set to the FQDN that IIS will be configured to serve. This is the address a user would type into their browser to access the application. For example:

• use <atlassianapp>.example.com to access the application at a sub-domain like http://<atlassianapp>.example.com/
• use example.com  to access the application at a context path like  http://example.com/<atlassianapp> . In this case, the context path should not be included in the proxyName parameter, and you would have already set the Context directive in step 2 above.
• use proxyPort="443" and scheme="https" in case the SSL is being terminate at IIS.

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

Part B. Configure Internet Information Services (IIS)

1. Be sure you have ARR, URL rewrite and Request Filtering installed on your IIS server

In case you do not have Application Request Routing and URL Rewrite on your IIS server install them using Application Request Routing Installer.

In case Request Filtering is not installed in your IIS instance you can install it following https://www.iis.net/configreference/system.webserver/security/requestfiltering.

2. Enable Proxying on ARR

1. From the IIS7 Console, click on Server_Name and  open Application Request Routing Cache:
   
2. From the Actions panel on the right hand side, select  "Server Proxy Settings"
    
3. Check "Enable Proxy" and set HTTP Version to "HTTP/1.1":
   
4. Deselect "Reverse rewrite host in response headers" then leave all the other options on the default value and click on Apply to apply the changes.

3. Add an Application Pool and new IIS website 

Create an Application Pool for Atlassian applications and change the the .NET CLR Version to "No Managed Code". Please see How to create a new application pool for more details. If your site is configured with Default Pool and it's being shared, and ASP.NET is registered with IIS, it may cause some unexpected behavior in Atlassian applications, especially for integration features like Smart commits etc.

Next step, create a IIS website to configure the redirect. More info on how to create a Web Site on IIS can be found at How to set up your first IIS Web site. Configure this website to use the Application Pool created in the earlier step.

4. Add a new URL rewrite rule

1. From the IIS Console, click on  jira.example.com  and open URL Rewrite:
   
2. From the Actions panel on the right hand side, select "Add Rules" and choose "Blank Rule";
3. Add a name for the rule;
4. Set Match URL to:
   1. Requested URL: Matches the Pattern
   2. Using: Regular Expressions
   3. Pattern: (.*)
   4. Ignore Case: Checked
5. Set Action to:
   1. Action Type: Rewrite
   2. Rewrite URL:  http://<JIRA_url:Port>/{R:1}
   3. Append query string: Checked
6. Mark Stop processing of subsequent rules;
7. Click on Apply to apply the changes.
   

5. Tune Request Filtering

1. Double-click on the site name to move in the site configuration section.

2. Click in Request Filtering. 
   

3. Then click in Edit Feature Settings:
   
4. Check Allow double escaping and hit OK:
   

6. Disable Output Caching

1. On the Site Home screen in IIS Manager double click on "Output Caching"
2. On the right side under Actions, click on Edit Feature Settings
3. Uncheck Enable Cache and Enable kernel cache
4. Click OK

7. Enable long URLs

Add a registry key as shown below to increase the path length that IIS can handle. This is necessary for some gadgets and buttons to work correctly.

Path: "HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\HTTP\Parameters"
Type: DWORD 32-bit
Name: "UrlSegmentMaxLength"
Value: "1000" Hexadezimal

Confluence 6.0 specific notes:

If you're using Confluence 6.0 or later with Synchrony (which is required for collaborative editing), you'll need to ensure the following prerequisites are met:

1. You must have IIS version 8.0 or higher installed
2. You must have Web Sockets Support for IIS installed
3. You must have Application Request Routing 3.0 installed

CONFSERVER-46504 - Getting issue details... STATUS

You'll also need to use the following rewrite rules in your web.config file:

<system.webServer>
    <rewrite>
        <rules useOriginalURLEncoding="false">
        <clear />
        <rule name="Synchrony HTTP" stopProcessing="true">
            <match url="^synchrony/(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8091/synchrony/{R:1}" />
        </rule>
        <rule name="Synchrony Web Sockets Reverse Proxy" stopProcessing="true">
            <match url="ws://(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="ws://localhost:8091/{R:1}" />
        </rule>
        <rule name="Unencoded URL for Companion" stopProcessing="true">
            <match url="^download/(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8090{UNENCODED_URL}" appendQueryString="false" />
        </rule>
        <rule name="Confluence Reverse Proxy" stopProcessing="true">
            <match url="(.*)" />
            <conditions logicalGrouping="MatchAll" trackAllCaptures="false" />
            <action type="Rewrite" url="http://localhost:8090/{R:1}" />
        </rule>
        </rules>
    </rewrite>
    <security>
        <requestFiltering allowDoubleEscaping="true" />
    </security>
    </system.webServer>
    <system.web>
        <!-- This keeps IIS from complaining about special characters in the url. Also has some controls for max upload size. Set to the equivalent of the above, but in kilobytes instead of bytes. (ex. 61440 = 60MB) -->
        <httpRuntime executionTimeout="20" maxRequestLength="xxxxx" requestPathInvalidCharacters="" requestValidationMode="2.0" />
        <pages validateRequest="false" />
    </system.web>

In the example above, Confluence is accessed without a context path and does not use Confluence's internal proxy. See Administering Collaborative Editing for other proxy configuration options.

As IIS 8.0 and above does not support the Sec-WebSockets-Extension permessage-deflate header, you will also need to add the following to your startup parameters:

• If you start Confluence via startup script on Windows or Linux, add the following parameter to your <install-path>/bin/setenv.bat or setenv.sh 

# For Linux/Unix setenv.sh
CATALINA_OPTS=-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true %CATALINA_OPTS%


# For Windows setenv.bat
set CATALINA_OPTS=-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true %CATALINA_OPTS%

• If your instance is installed as a Windows service, add the following system property via command line or registry. See Configuring System Properties guide for instructions:

-Dorg.apache.tomcat.websocket.DISABLE_BUILTIN_EXTENSIONS=true

Part C. Final configuration

Restart each application

Now, restart each application and ensure you can access them using new URLs. See the stopping and starting instructions above.

Set the application Base URL

For each Atlassian application, set the Base URL to the address you configured in the proxy, which is the URL that Internet Information Services (IIS) will be serving (such as  http://www.example.com/<atlassianapp>).

For details see the instructions for your Atlassian product:

• Jira
• Confluence
• Bamboo
• Bitbucket
• Fisheye / Crucible
• Crowd

Part D. Configure Multiple Sites on the same IIS instance

OPTIONAL: In some cases more than one site will be hosted in the same IIS installation. In case you want to have a subdomain structure (i.e. jira.example.com, confluence.example.com), you may create different sites as follow: