Configure your CDN for Bitbucket Data Center

Use a CDN with Atlassian Data Center applications

On this page

Still need help?

The Atlassian Community is here for you.

Ask the community

On this page:

If your users are distributed across the world and experience high latency when using Bitbucket Data Center, you may be able to improve their experience by using a Content Delivery Network (CDN). Common CDNs include AWS CloudFront, Cloudflare, Azure CDN, Akamai, and others. 

Head to Use a CDN with Atlassian Data Center applications to learn about our CDN capabilities, and how to assess whether it will improve your users' experience. 

Once you're ready to start using a CDN, there are three main steps:

  1. Configure an internet-facing load balancer (optional)
  2. Configure your CDN. 
  3. Enable the CDN feature in Bitbucket Data Center. 

Configure an internet facing load balancer (optional)

If your site is not publicly accessible, you'll need to make sure that your CDN can reach it, but only to access and cache static assets.  The way you do this depends on your particular load balancer and web application firewall. Refer to the documentation for your load balancer and firewall for detailed guidance. 

Add an internet-facing load balancer

Add an internet-facing load balancer to your setup. This is in addition to your primary load balancer. Your CDN is the only entity that will interact with this load balancer. We recommend you:

  • Enable HTTPS - the traffic from this load balancer will be sent over the public internet and should be encrypted.
  • Enable HTTP/1.1 - currently, the caching proxies and CDNs do not handle HTTP/2 well (or at all) on the way to the origin.
  • For AWS deployments, you would set up an internet-facing application load balancer.

Update your firewall rules for the internet-facing load balancer

Unlike your primary load balancer, this internet-facing load balancer must be locked down to ensure that your CDN can only pull data it is allowed to cache. When configuring your firewall rules we recommend:

  1. The configuration should only allow requests for paths that start with "/s/".  If your application is deployed with a context path (for example yoursite.com/wiki or yoursite.com/jira) you will need to include it in the path. All other requests must be blocked. 
  2. You can also choose to limit the allowed HTTP methods to GET, HEAD, OPTIONS.

For AWS deployments, you will configure a Web Access Control List (WebACL) in the Web Application Firewall attached to your application load balancer. The condition to use is a "string match condition"  applied to "URI". 

To check that your setup is secure, perform the following manual tests:

  1. A GET on https://internet-facing-proxy/  should return "403 FORBIDDEN".
  2. A GET on https://internet-facing-proxy/s  should return "403 FORBIDDEN".
  3. A GET on https://internet-facing-proxy/s/  should return "404 NOT FOUND".
  4. A GET on https://internet-facing-proxy/s/.  should return "403 FORBIDDEN".
  5. A GET on https://internet-facing-proxy/s/../s/  should return "404 NOT FOUND".

Configure your CDN to cache assets

You'll need an account with a CDN provider. You're responsible for all costs associated with your CDN. We only support serving static assets from a CDN at this time. This means page content, attached files, and personally identifiable information, including things like user avatars, won't be cached by your CDN.

We've prepared a CloudFormation template that you can use to configure Amazon CloudFront with minimal effort. You can find all our AWS deployment resources in this repository https://bitbucket.org/atlassian/atlassian-aws-deployment/src/master/templates/cdn/

If you choose not to use our template, define the following in your CDN configuration.  This example is based on AWS CloudFront. 

Origin domain nameThis is your Atlassian application base URL, including the context path if you've configured one. 
For example: mycompany.com/confluence  
Origin path

Leave blank. There is no need to specify a path.

Allowed HTTP methodsOptionally limit to: GET, HEAD, OPTIONS
Viewer protocol policyredirect HTTP to HTTPS
Object cachingUse origin cache headers
Forward cookiesNone
This is important to make sure static assets are cached without the user context.
Query String Forwarding and CachingForward all, cache based on all
HTTP protocolsMust include HTTP/2
Error pages/Error Caching Minimum TTL (seconds)The default error page caching time for CloudFront is 5 minutes. Consider lowering it to a value in the range of 10-30 seconds to decrease the time required to recover from an outage.

Compress Objects Automatically

Yes

Using the default should be fine for most of the other settings. 

You will need to adapt this information for your particular CDN provider. You should refer to the documentation for your CDN for details, as we've found that terminology differs between CDNs.

Enable CDN in Bitbucket Data Center

Once you've configured your CDN, you can enable the CDN option in Bitbucket Data Center.  

To turn on CDN:

  1. Go to Admin > Content Delivery Network
  2. Navigate to the Settings tab. 
  3. Set the status to On
  4. Paste the URL generated by your CDN into the URL field and hit Validate
  5. If successful, save your changes. 

As end users access Bitbucket in their browser, static assets will be cached on the edge server closest to them, and served from there until they expire.  This means it might take some time before you can start measuring the impact of the CDN, depending on when your users are online and accessing the site in each location.

Configure CDN in Bitbucket via REST

You can also interact with the CDN feature using the following REST endpoint: <base-url>/rest/static-asset-caching/configuration
  • GETreturns the current CDN status, and URL.
  • DELETEdeletes the existing configuration and reverts to the default state (CDN disabled, no URL). This is useful if you can't access the UI because of a caching problem.
  • PUTsets the CDN URL and status to the values passed in the body of the request as follows: 
     

    {
      “enabled”: true, 
      “url”: “https://yourcdnurl.com”
    }


Troubleshooting

Here are some common problems that you may encounter. 
  • We only accept HTTPS CDN URLs 
    This is particularly important if you're using Azure CDN, as Azure CDN will mirror the same protocol as the originating request, which means your Data Center application will need to be provisioned with HTTPS. 
  • Data Center application UI is inaccessible or not functional
    Although unlikely, a misconfiguration of your CDN or a CDN service outage may mean your application's UI is not accessible. If this happens, you will need to disable the CDN feature using the REST API, as follows.  

    curl -v -u <admin username>:<admin password> -X DELETE http://<your-base-url>/rest/static-asset-caching/configuration

    This example uses Curl, but you can use any language. Don't forget to replace the username, password, and base URL placeholders with your own details.  

  • HTTP/2 disabled
    Your load balancer, firewall, or reverse proxy should allow HTTP/2 traffic. Using HTTP/2 will provide the best performance for your end users. See HTTP/2 health check fails in Data Center when configuring CDN for more information. 
  • User-installed apps may not be compatible
    This warning is displayed when we detect that a Marketplace or other user-installed app is using a deprecated method, which may result in assets being cached incorrectly. See User-installed apps health check fails in Data Center when configuring CDN for more information on what to do if you see this warning. 

Frequently asked questions

Can I control what static assets are cached? 

No, the application controls this. All requests for static assets are routed to the CDN. Requests for non-static assets are routed directly to your product. 

Is personally identifiable information cached? 

User created content, usernames, mentions, avatars etc are not static assets, so are not cached. Your CDN should also be configured to pull content from your product with cookies stripped to make sure it operates without user context. 

Is dynamic content such as batch.js cached? 

Although dynamically generated, batch.js is considered static content, so is cached. 

Last modified on Jan 31, 2023

Was this helpful?

Yes
No
Provide feedback about this article
Powered by Confluence and Scroll Viewport.