Custom Domains and SSL

Once your site is upgraded to the paid plan, you can configure your site to be served on a custom domain. Aerobatic will provision a wildcard SSL certificate for your domain using the AWS Certificate Manager. Wildcard certificates cover your apex, aka “naked”, domain and all subdomains. This allows you to cover all your deploy stages using the same certificate, for example:

  • https://www.mydomain.com
  • https://www--test.mydomain.com
  • https://www--develop.mydomain.com

Depending on your DNS provider (more on this below), you can use apex (aka “naked”) domains:

  • https://mydomain.com
  • https://test.mydomain.com
  • https://develop.mydomain.com

You can also re-use the same domain + certificate across multiple paid websites:

  • https://www.mydomain.com
  • https://blog.mydomain.com

Registering your domain

Registering a new custom domain with wildcard certificate is done via the CLI. From the root of the website that you want to attach the domain, simply run the following command:

$ aero domain --name mydomain.com --subdomain www

Or if you want to run your site at the apex (i.e. “naked domain”), then specify “@” as the sub-domain:

$ aero domain --name mydomain.com --subdomain @

See the aero domain command for more details.

Domain ownership validation

The first step after running the aero domain command is to validate you are the owner of the domain. This is done by creating a special CNAME record with your DNS provider. Very soon after you request the domain with the command above, an email will be sent to you with the CNAME details. You can also run the aero domain command again (without any arguments) which will provide the same info.

The validation record will look something like so:

Record Name Value
CNAME _3639ac514e785e898d2646601fa951d5.yourdomain.com _fbc6a92e9dedgh546e4b606a613d305.acm-validations.aws.

If interested, you can read more about the validation process in the ACM documentation.

Some domain registrars such as Namecheap do not allow an “_” character in a CNAME value. In this case you will need to transfer your nameservers over to a different DNS provider. We recommend any of the providers listed in the apex domains section below. Cloudflare is free to use for basic DNS services, see our Namecheap to Cloudflare directions.

Once domain ownership is validated, the domain provisioning process will commence. This takes roughly 40 minutes to complete. Once complete, you will receive an email from support@aerobatic.com with instructions on how to configure the actual DNS records that cause your domain to resolve to the Aerobatic CDN. You can also run the aero domain command (with no arguments) to get the latest status.

Do NOT delete the validation CNAME. It will be re-checked every time the SSL certificate is auto-renewed.

DNS Settings

Once your domain is provisioned on the Aerobatic CDN, the next step is to create records with your DNS provider so that your domain resolves to your Aerobatic website. We recommend a single wildcard (aka catch-all) CNAME if your domain provider supports it. That way you only have to configure a single DNS record that covers all website subdomains and staging aliases.

Record Name Value
CNAME * [your_dns_value].cloudfront.net

Any named subdomain CNAMEs that point somewhere other than Aerobatic will take precedence over the wildcard (so the same domain can be used for non-Aerobatic sites). If you prefer not to use a wildcard, or your DNS provider doesn’t support it, you can of course create each CNAME separately:

Record Name Value
CNAME www [your_dns_value].cloudfront.net
CNAME blog [your_dns_value].cloudfront.net
CNAME www--staging [your_dns_value].cloudfront.net

Apex domains

The apex or “naked” domain is the root domain, sans any subdomain, i.e. https://yourdomain.net. Many prefer this simplified format for their website URLs. As long as your DNS provider supports CNAME-like functionality at the zone apex you can load your Aerobatic websites via their apex URL. Providers generally refer to these as ALIAS or ANAME records. Here are some of the providers that have an offering:

Domain providers that support one of the flavors of CNAME-like at the apex include:

Some providers, such as Namecheap, technically allow you to define a CNAME record @ that will route your apex domain correctly. But be aware, this will likely break email for your domain. This is because the @ record takes precedence over any MX mail records.

We suggest you ONLY utilize the apex domain if your DNS provider has special ALIAS/ANAME record types specifically intended to handle it. The alternative is a CNAME for each website like www.

Apex workarounds

If your DNS provider does not support ANAME or ALIAS records and it’s not possible to switch, then your best bet is to redirect the apex URL to a CNAME like www. Below are two possible ways to configure this:

  • Many providers let you define a URL redirect record that will redirect the apex to any URL of your choice. In this case you would want to point to https://www.mydomain.com.

  • Use a service called ARecord which provides a static IP address to assign to an A record. Their service will redirect requests from the apex to www sub-domain.

These redirect solutions only work for an http request, NOT https. If a user types “yourdomain.com” into their browser, the above solution will work since the browser defaults to http in the absence of a protocol. But the ONLY way to make https://yourdomain.com work is to use one of the aforementioned DNS providers that support ANAME or ALIAS record types.

Cloudflare Setup

When using Cloudflare in front of your Aerobatic custom domain there are a few considerations to keep in mind:

  • You can use the CNAME flattening feature to make your site available at the apex domain.
  • We recommend that you disable the Cloudflare proxy and use the “DNS Only” mode. This is done by clicking the orange cloud next to the DNS record so that it runs into a gray cloud with an arrow over top.

If you do choose to enable the Cloudflare Proxy/CDN functionality, then make sure the following settings are made:

  • You must set SSL to “Full” to avoid your site getting caught in a redirect loop. [CloudFlare docs].
  • In order to force CloudFlare to use the HTTP headers set by Aerobatic make sure to set the “Respect Existing Headers” option. [CloudFlare docs]

Route 53 setup

If your current domain provider does not provide ALIAS/ANAME record types and you really want to host your site on the apex domain, we recommend transferring your name server records to Amazon Route 53. Route 53 can has a special relationship with CloudFront which is the CDN that Aerobatic uses to host your custom domain and SSL certificate.

You’ll want to create two record sets, an A record for your apex domain and a second CNAME for your www subdomain which will automatically redirect to your apex domain as long as the website subdomain is set to @ in the Aerobatic hosting settings.

Name Type Alias Alias target or Value
<blank> A - IPv4 address Yes [domain_dns_value].cloudfront.net.
www CNAME No [domain_dns_value].cloudfront.net

Namecheap to Cloudflare

Namecheap is a popular service for getting a good deal on a domain name, but their DNS management leaves much to be desired. In addition to not supporting ANAME records for apex domains, it also does not support the \_ character in a CNAME which the domain validation record requires. For many users, the easiest and cheapest solution is to transfer the domain nameserver over to Cloudflare.

  1. First you’ll need to create an account on Cloudflare
  2. In the Cloudflare dashboard, click the Add site button and enter your domain name
  3. Follow the wizard steps to setup your Cloudflare site
  4. Transfer your nameservers in the Namecheap dashboard to the values provided by Cloudflare

Namecheap Cloudflare custom nameservers

Now you should be able to create the validation CNAME in Cloudflare without any problems. Your final set of DNS records when fully configured for Aerobatic will look something like below. The 2nd CNAME record with the leading “_” is the domain validation record. The others are for the actual custom domain resolution to your Aerobatic CDN distribution.

Note the grayed out icon in the Status column. This indicates that only the Cloudflare DNS services are being utilized.

Cloudflare DNS records

In order for your apex (aka naked) domain to resolve to Aerobatic you need to use Cloudflare CNAME flattening. First delete the automatically generated A record that points to an IP address. Then create a CNAME with the value “@” that points to the *.cloudfront.net domain assigned to your Aerobatic domain. The 3rd record in the screenshot above represents the flattened apex CNAME.

Related links

Apex domains and deploy stages

When using deploy stages for websites whose production URL is at the apex, the stage name becomes a subdomain:

  • https://mydomain.com <– production
  • https://staging.mydomain.com
  • https://test.mydomain.com