Custom Domains and Reverse Proxies | K15t

Confluence itself does not support multiple domains out of the box, however this is desired for certain Scroll Sites use cases.

If your Confluence installation sits behind a reverse proxy and you want to run a viewport on a domain that is different from the Confluence base URL, you may have to make some changes to your networking setup to ensure that everything works correctly.

Common effects of an incomplete configuration are:

Viewports with a custom domain name are not reachable
Confluence rejecting certain requests whose server name does not match the name of the host.
- For example: POST requests to /rest/webResources/1.0/resources that fail with a status code of 403

We recommend to use the proxy debugger tool within Viewport to debug your settings to identify possible issues during the setup.

Required Configuration Changes

There are several ways to configure Confluence / Tomcat and a reverse proxy to support multiple domains in Scroll Sites, each with certain drawbacks and benefits.

If you just want to configure one additional domain, choose approach 1. If you need many additional domains, choose approach 2.

Approach 1: Additional Tomcat Connector

For this approach we'll configure a separate Tomcat listener for the additional domain.

Properties of this approach:

Simple to set up

Compatible with Confluence setup checks

Requires additional memory for the threads serving requests for the new connector (1MB per thread configured in maxThreads attribute)

Configuration overhead when many additional domains are required

Tomcat Configuration

In server.xml find the enabled connector. It should look like this:

Original server.xml

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
           maxThreads="48" minSpareThreads="10"
           enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           scheme="https" proxyName="wiki.example.com" proxyPort="443"/>

Now copy it and adapt the port and proxyName attributes:

Modified server.xml

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
           maxThreads="48" minSpareThreads="10"
           enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           scheme="https" proxyName="wiki.example.com" proxyPort="443"/>

<Connector port="8095" connectionTimeout="20000" redirectPort="8443"
           maxThreads="48" minSpareThreads="10"
           enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           scheme="https" proxyName="docs.example.com" proxyPort="443"/>

Set the attributes as follows:

port needs to be set to an unused port. Please note that synchrony be default runs on port 8091.
proxyName should contain the additional domain name.
proxyPort should be the same for both connectors unless the reverse proxy uses different ports for the virtual hosts.

Changes to server.xml require you to restart Confluence to have any effect.

Reverse Proxy Configuration

You need to create a separate virtual host in your reverse proxy configuration. Here's the NGINX example from Atlassian's docs:

server {
    listen 443;
    server_name wiki.example.com;
    location /confluence {
        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://localhost:8090/confluence;
    }
}

Now copy this server block and adapt the server_name and proxy_pass directives, so they match the additional domain and the respective connector port:

server {
    listen 443 ssl;
    server_name wiki.example.com;
	...
    location /confluence {
        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://localhost:8090/confluence;
    }
}


server {
    listen 443 ssl;
    server_name docs.example.com;
	...
    location /confluence {
        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://localhost:8095/confluence;
    }
}

Don't forget to restart the reverse proxy.

Approach 2: Shared Tomcat Connector for multiple Domains

For this approach we'll configure a single Tomcat connector so it supports multiple domains.

The actual domain used by requests will be extracted from a HTTP header which needs to be set by the reverse proxy.

Properties of this approach:

Does not require additional memory for multiple tomcat connectors

No Confluence configuration updates and restart required when adding further domains later on

Not compatible with Confluence setup checks. Confluence system administrators will get warnings from Confluence. Disable the "Confluence Base Url Plugin" to suppress.

More complicated to set up initially

Atlassian support might not be aware of this setup

Tomcat Configuration

In server.xml find the enabled connector. It should look like this:

Original Connector

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
           maxThreads="48" minSpareThreads="10"
           enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"
           scheme="https" proxyName="wiki.example.com" proxyPort="443"/>

Now remove the attributes related to the proxy: scheme, port and proxyName.

Modified Connector

<Connector port="8090" connectionTimeout="20000" redirectPort="8443"
           maxThreads="48" minSpareThreads="10"
           enableLookups="false" acceptCount="10" debug="0" URIEncoding="UTF-8"
           protocol="org.apache.coyote.http11.Http11NioProtocol"/>

Next find the Context element in server.xml (the path attribute might be different, depending on your setup):

Original Context

<Context path="" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
    <!-- Logging configuration for Confluence is specified in confluence/WEB-INF/classes/log4j.properties -->
    <Manager pathname=""/>
    <Valve className="org.apache.catalina.valves.StuckThreadDetectionValve" threshold="60"/>
</Context>

Finally add another Valve element as follows. This valve will extract the original request's domain name and provide it to the connector.

Modified Context

<Context path="" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
    <!-- Logging configuration for Confluence is specified in confluence/WEB-INF/classes/log4j.properties -->
    <Manager pathname=""/>
    <Valve className="org.apache.catalina.valves.RemoteIpValve" remoteIpHeader="x-forwarded-for" protocolHeader="x-forwarded-proto" />
    <Valve className="org.apache.catalina.valves.StuckThreadDetectionValve" threshold="60"/>
</Context>

Changes to server.xml require you to restart Confluence to have any effect.

Reverse Proxy Configuration

The RemoteIpValve requires several additional HTTP headers to retrieve the original request data from.

Here's the NGINX example from Atlassian's docs:

server {
    listen 443 ssl;
    server_name wiki.example.com;
    location /confluence {
        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://localhost:8090/confluence;
    }
}

Now add headers as follows:

Nginx vhost definition

server {
    listen 443 ssl;
    server_name wiki.example.com;    
    ...
    location / {
        proxy_set_header Host $host;
        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_set_header X-Forwarded-Ssl $https;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Port $server_port;

        proxy_pass http://localhost:8090;
    }
}

Repeat such a server block for each domain you require.

Don't forget to restart the reverse proxy.