Using External Domain for Pages

Configuring Pages for Bitbucket to serve through an external domain allows you to host arbitrary Javascript and CSS without the risk of XSS vulnerabilities. When pages are served via another domain, the browser’s same-origin policy helps to ensure that no Bitbucket session information is available in malicious javascript.

Effects of enabling serving via an external domain

All pages served are available publicly since Bitbucket authentication is not available.
Javascript and CSS sanitization is turned off since it is not required.
Attempting to access content at the old URL results in a redirect to the new location at the external domain.

Enable serving via external domain

Highlight of the External Domain section of the Pages configuration page

When Pages Domain is enabled, all repository content is available to anonymous users.

An external domain is enabled by specifying a Pages Domain on the global Pages configuration page available to administrators.

Click the Administration icon > Pages configuration to open the Pages configuration page.
In the External Domain > Pages Domain text field, provide your custom domain. This can be any domain other than the Bitbucket domain.
Click Save.
To turn off the external domain configuration, clear the Pages Domain field and click Save.

Selecting a sub-folder to serve

Highlight of the Sub-folder to serve field on the Web pages page

This option is available for versions 3.7.0 and higher.

The Sub-folder to serve option is intended to use along with the external domain. When configured, anonymous users can only access files in the specified folder. This is useful for cases when no access to the source code is required, but generated documentation needs to be available for everyone.

The folder becomes a root folder for the web server, and the configured folder name shouldn’t be a part of external URLs.

If an external folder is not configured, the option does not affect the web server.

Select a repository and click Repository settings > Web Pages to open the Web pages page.
Enter the path used as root of web server in the Sub-folder to serve field and click Save. Using this option limits access to the repository through the web server. Only the contents of the specified folder are served as pages.

Configuring a reverse proxy

The external domain pages domain must be configured to re-direct to Bitbucket using a reverse proxy. For some background on configuring a reverse proxy: reference 1, reference 2.

Under the hood, the plugin checks the X-Forwarded-Host header to determine if a request was made through the pages domain.

Apache example configuration:

Example - Virtual host configuration for the Apache HTTP server:

<VirtualHost *:80>
    ServerName bitbucket-pages.local
     
    ProxyRequests Off
    ProxyVia Off
     
    <Proxy *>
         Require all granted
    </Proxy>
 
    ProxyPass /pages http://localhost:7990/bitbucket/pages
    ProxyPassReverse /pages http://localhost:7990/bitbucket/pages
</VirtualHost>

Nginx example configuration:

worker_processes  1;

events {
    worker_connections 1024;
}

http {
    server {
        listen 8080;
        server_name bitbucket-pages.local;

        location /pages/ {
            proxy_pass http://localhost:7990/bitbucket/pages/;
            proxy_set_header X-Forwarded-Host $host;
        }
    }
}