📘 This article assumes that you have created an Endpoint for your App, and that you have the Endpoint Hostname (the string that looks like elb-XXX.aptible.in) in hand.

If you don’t have that, start here: How do I expose my web app on the Internet?.

As noted in the Custom Domain documentation, Aptible requires that you create a CNAME from the domain of your choice to the Endpoint Hostname. Unfortunately, DNS does not allow the creation of CNAMEs for domain apexes (also known as “bare domains” or “root domains”). There are two options to work around this problem and we strongly recommend using the Redirect option.

​
Redirect to a Subdomain

The general idea behind setting up a redirection is to sidestep your domain apex entirely and redirect your users transparently to a subdomain, from which you will be able to create a CNAME to an Aptible Endpoint Hostname.

Most customers often choose to use a subdomain such as www or app for this purpose.

To set up a redirection from your domain apex to a subdomain, we strongly recommend using a combination of AWS S3, AWS CloudFront, and AWS Certificate Manager. Using these three services, you can set up a redirection that is easy to set up and requires absolutely no maintenance going forward.

To make things easier for you, Aptible provides detailed instructions to set this up, including a CloudFormation template that will automate all the heavy lifting for you.

To use this template, review the instructions here: How do I set up an apex redirect using Amazon AWS.

​
Use an ALIAS record

Setting up an ALIAS record lets you serve your App from your domain apex directly, but there are significant tradeoffs involved in this approach:

First, this will break some Aptible functionality. Specifically, if you use an ALIAS record, Aptible will no longer be able to serve your Maintenance Page from its backup error page server, Brickwall. In fact, what happens exactly will depend on your DNS provider:

  • Amazon Route 53: no error page will be served. Customers will most likely be presented with an error page from their browser indicating that the site is not working.

  • Cloudflare, DNSimple: a generic Aptible error page will be served.

Second, depending on the provider, the ALIAS record may break in the future if Aptible needs to replace the underlying load balancer for your Endpoint. Specifically, this will be the case if your DNS provider is Amazon Route 53. We’ll do our best to notify you if such a replacement needs to happen, but we cannot guarantee that you won’t experience disruption during said replacement.

If, given these tradeoffs, you still want to set up an ALIAS record directly to your Aptible Endpoint, please contact Aptible Support for instructions.

📘 Both approaches require a provider that supports ALIAS records (also known as CNAME flattening), such as Amazon Route 53, Cloudflare, or DNSimple.

If your DNS records are hosted somewhere else, you will need to migrate to one of these providers or use a different solution (we strongly recommend against doing that).

Note that you only need to update the NS records for your domain. You can keep using your existing provider as a registrar, and you don’t need to transfer the domain over to one of the providers we recommend.

Keep reading: