Setting up a custom domain in the Confluence cloud using Cloudflare Tunnel

Introduction

CLOUD-6999, the request to enable custom domains for Confluence Cloud, is now 12 years old from when the issue was first created. Maybe someday I'll be able to use custom domains, but I need them now that I’m hosting my personal websites on Confluence Cloud, so I can't just wait. For a while, I used a service called cloak.ist and it worked fine, but a number of features didn't work, and when I first used it, it said it supported Confluence, but later I realized that not only had the Confluence support message disappeared, but there was no feedback at all on my feature requests, so I decided it wasn't good enough to continue paying for it. After a long and frustrating wait, I began to wonder if Atlassian was never going to support custom domains, and if so, what were the alternatives?

In early 2023, Atlassian even tested the patience of the user community by sharing a bizarre illustration of what would surely be a two-tiered subdomain after 12 years of work. Personally, I think it was a brilliant move, as it succeeded in diverting attention away from what had been a mere wait for custom domain support by presenting a single mockup image. Unfortunately, I don't expect anything to come of it beyond that illustration.

I can't just wait around for Atlassian to support custom domains, and maybe one day they will miraculously do so, but it's been a long 12 years, and I don't think it's too much to ask or too much to expect that they'll release a bunch of drawings and make us wait a few more years. So I'm going to show you how you can use custom domains in a way that you can apply right now, in 2023.

What you can and can't do

First, let's explain what you can and cannot accomplish with this guide. You can expose a space that you set as public in Confluence Cloud as a custom domain using the Cloudflare tunnel. You can replace an existing Atlassian domain with a custom domain.

  • You cannot change the path under your domain, so the path through your custom domain will still use the same "wiki", "space", "pages", and space name.

  • Several features don't work in the Confluence Cloud through a custom domain.

  • All features that require a login are unavailable.

  • Search won't work.

  • Many commonly used macros don't work. I'll provide a list of the ones I've identified later.

Despite these issues, I'm able to service the Confluence Cloud through a custom domain at about the same level as what I was previously paying for through a third-party service, which is good enough for me as someone who uses Confluence Space as a personal website.

Preparation

Next, let's talk about what you need to bring.

  • You must have a site in the Confluence Cloud and be able to make your space public by subscribing to the Standard plan or higher.

  • You must have an account on Cloudflare. The Cloudflare Tunnel is free to use, so you don't need to be on any paid plan.

  • You'll need a server to run the Cloudflare tunnel on. I’m going to create an instance on AWS Lightsail, but I know there are free instances available on Oracle Cloud Infrastructure, so I'll be moving there in the near future.

How it works

Cloudflare Tunnel is a reverse proxy service that can be installed on a machine inside a specific network to open a tunnel between Cloudflare and the machine, exposing the machine's accessible network to the Internet without any network configuration. It seems like it's primarily intended to be used to securely access resources on your local network from the internet, but the tunnel doesn't restrict access to the outside internet beyond the machines on your local network, so what you want to do is set up a custom domain in the Cloudflare tunnel and set the target to be accessed through the tunnel to be the Confluence Cloud, and make the Confluence Cloud available to the custom domain.

I apologize for the lengthy explanation. Let's get started.

Procedure

Create a Cloudflare tunnel

  • Log in to Cloudflare and open the Zero Trust dashboard.

  • Open the Access -> Tunnels menu.

    • You'll see a list of tunnels you've already created, but if this is your first time creating a tunnel, the list will be empty.

    • The screenshot shows that a tunnel named confluence-tunnel has already been created and is serving docs.woojinkim.org.

  • Click the Create a Tunnel button.

Name the tunnel. This name doesn't affect the service, so feel free to name it anything. For my purposes, I'll call it confluence-tunnel-tutorial. Click the Save tunnel button to save it.

The tunnel has been created. The tunnel entrance has been created in Cloudflare, but there is no tunnel exit yet. We need a server to be responsible for the tunnel exit. Don't close the tab at this point, it's time to open a new tab and create a tunnel exit server. I'll use AWS Lightsail here, but you can use any other service.

Create a tunnel server

Open your Lightsale dashboard. The screenshot is in Korean, but the menu order and button locations should be the same in other languages. You'll see the cloudflare_tunnel instance that I’m using to serve the Confluence custom domain. I’m going to create a new instance and connect a new custom domain to it.

Click the 'Create Instance' button. If you can't read English, it's the top right orange button in the screenshot.

You'll need to select a Blueprint, and since I’m only going to use this server for one thing - servicing the Confluence Cloud - I’m chosen Ubuntu for the OS.

Set the instance name. For this example, I'll call it confluence-cloud-custom-domain-tutorial.

When you're ready, click the Create Instance button to create an instance.

Install cloudflared

While your Lightsail instance is starting, go back to the Cloudflare tab and click the Debian button and then the 64 bit button.

Scroll down and you will see the commands for installing cloudflared on the new server. Since I just started a new server, copy the command shown on the left.

Your Lightsail instance should have started in the meantime. Click the >_ button to connect to the server.

Paste the command copied from cloudflare and run it. You can also use docker to install cloudflared. For this tutorial, I chose to install directly into the OS instead of docker because I chose the lowest specification instance, so it might not be comfortable running through docker. If you choose a higher specification instance, you should be fine using docker. You can also run containers directly on Lightsail, so you might be more comfortable that way.

Wait for the command to finish executing. It should finish running in a few seconds.

Back in Cloudflare, click the Save button at the bottom right of the screen.

Connecting custom domain and Confluence Cloud address

Now we need to set up a custom domain to serve as the tunnel entrance and a Confluence Cloud address to serve as the tunnel exit. Go up to the top of the screen, click the Public Hostname tab, and then click the Add a public hostname button.

The Public hostname at the top is the custom domain that users will actually enter. Here, I've set the subdomain to custom-domain, which uses a one-level subdomain as opposed to the two-level subdomain suggested in the illustrated 'Custom Domains in Cloud - Development Update'.

The bottom is the Confluence cloud address that the service will actually connect to. You can only specify up to a 'domain name' here, and you can't use subpaths, so you need to set up redirects, which I'll talk about later. For the Type, enter HTTPS, and for the URL, enter the address of the Confluence Cloud that you want to actually connect to. You don't need to enter a port number, it will be set to 443 on its own.

Click Additional application settings at the bottom, and then click HTTP Settings. You will see the HTTP Host Header, where you will enter your Confluence Cloud domain. This is important because if you don't enter this host header and access it through your custom domain, Atlassian website will always display the maintenance screen. You don't need to touch any of the other options. Click the Save hostname button.

Redirect settings

Now that we've set up your custom domain and the Confluence Cloud website that will be accessed through it, let's try to access it through the custom domain you set up.

If you enter a custom domain, it will take you to the Atlassian login page, where you will be redirected to your Atlassian domain, so you can only serve public spaces. If you type in the exact address of your Confluence with just the domain part replaced, it will work, but it's handy to have it redirect to your Confluence if you type in just the domain part instead of the full address.

Navigate to the Cloudflare dashboard. This is Cloudflare's website dashboard, not the Zero Trust dashboard I've been using. You can get there by clicking on your site name on the Cloudflare main screen. From there, click Rules -> Page Rules. We want to redirect people to the Confluence address when they request a custom domain. Click the Create Page Rule button.

For URL, enter the address of your Confluence custom domain. When this address is requested, we intend to redirect it to your Confluence page address. Here, I've entered custom-domain.woojinkim.org. When you request this address, It’ll going to take you to the front page of the Confluence cloud.

Then set the settings are part. Under Pick a Setting, I chose Forwarding URL and under Select status code, I chose 301. In Enter destination URL, set the path to the Confluence Cloud to redirect when requesting a domain based on "Custom Domain". Click the Save and Deploy Rule button.

Test

Verify that the page redirect rule is entered.

Now try requesting your custom domain in your browser. Just enter the domain part and you'll be redirected to the first page. All links to the Confluence Cloud that appear on subsequent pages will change to your custom domain. In my experience, there are times when it redirects to the Atlassian domain under certain conditions, but I haven't figured out exactly what those are. Now you're all set. Feel free to adjust the instance you created on Lightsale based on the number of visitors and their experience, use an on-premises server, or move to a free cloud service.

Things that don't work

However, as I've discussed, this method is not foolproof. Here are some of the issues I've encountered when using this method to expose the public space of Confluence Cloud through a custom domain.

First, the site is not searchable. It works fine under the Atlassian domain, but under the custom domain it shows no results. I'm using Google search to expose the address through the custom domain to search instead. Confluence Cloud doesn't allow Google search, but with a custom domain you can expose it to Google search. I'll explain how to do this in another post.

Also, commonly used macros are not working. The only macro that works well in both desktop and mobile environments is:

  • child display

Other macros that work well on mobile but not on desktop, or that work well when you open the page from a link to another page but not when you use the page address directly:

  • include

  • excerpt include

  • multi excerpt include

  • youtube

  • iframe

  • google calendar

  • orderly

  • page property

  • page property report

  • mermaid

I would expect the list of macros that don't work to be much longer.

Conclusion

Despite these drawbacks, I needed a custom domain to run my personal website in a public space on the Confluence Cloud, and since it was for personal use, I decided to accept the drawbacks described above. Atlassian has a history of ignoring the needs of its users over the past 12 years, and I don't expect them to provide custom domain functionality in the near future, so my trust in Atlassian has been shattered in this regard. It's not perfect, but it's still possible to use the Confluence Cloud with a custom domain and be visible in Google search.

Assuming Atlassian doesn't block this method, I'm going to forget about CLOUD-6999 for a while, not get angry about this issue, and make peace with it for a while. I'm not a web expert, so there may be potential security issues with this method or various other issues that I haven't considered. However, leaving a reply to CLOUD-6999 will send an email to thousands of people, which doesn't seem like the best way to go, so if you have any suggestions, better methods, or comments on what I've written, please let me know via the following contacts