How do I connect a domain to my Heroku app?

Issue

You want to connect a domain or domains to your Heroku app. (Or your domain isn't working.)

Resolution

There are several steps involved with setting up a domain to work with Heroku and depending on your needs and situation, the way you have to setup your domains will differ. Here is a general overview that will work for most apps running on Heroku.

The following assumes you are using Heroku’s ACM to automatically manage SSL for you. This scenario is what the vast majority of apps will use.

• If you are going to manage your SSL yourself, see this article on SSL at Heroku.

• If you are confused about whether you should use ACM or SSL, see Understanding SSL On Heroku

Steps

1. Purchase your domain from a Domain Registrar. Note: Heroku does not host domains and you cannot buy a domain through Heroku.

2. Determine the types of domain(s) you would like to add to your Heroku App. See our types of domains section for further info.

3. Determine the types of records you need to set in your DNS Provider. See our types of Records section for further info.

4. Determine if your DNS Provider allows for you to add ANAME, ALIAS or FLATTENING Records. Please see the section Does My DNS Provider allow me to set ANAME, ALIAS or FLATTENING Records section for further info.

If your DNS Provider does not allow for ALIAS, ANAME or FLATTENING Records see My root domain isn’t working, what’s wrong? for alternative solutions.

5. Add your domain(s) to your Heroku app using heroku domains:add www.example.com. Eg;

$ heroku domains:add example.com
Configure your app's DNS provider to point to the DNS Target tetrahedral-example-wlxb5fi5rq556aabbcc3459.herokudns.com
For help, see https://devcenter.heroku.com/articles/custom-domains
                                                                   
The domain example.com has been enqueued for addition
Run heroku domains:wait 'example.com' to wait for completion
Adding example.com to ⬢ example-app-name... done

6. Get your DNS Target for each of your domains using heroku domains. Eg;

$ heroku domains
=== example-app-name Heroku Domain
example-app-name.herokuapp.com

=== example-app-name Custom Domains
Domain Name      DNS Record Type      DNS Target
example.com         ALIAS or ANAME       theoretical-example-aa9999tttuuuuu9ee33oo54.herokudns.com
test.example.com    CNAME              example-unicorn990088erd5566e3x1a8p9l3e.herokudns.com

7. In your DNS Provider set the appropriate record for each of your domains. Point the DNS Record at the DNS Target found in step 6. Eg;

Using the details in Step 6; 2 records need to be set in the DNS Provider;
1 - is an ALIAS, ANAME or FLATTENING record for the domain example.com that points to the DNS Target: theoretical-example-aa9999tttuuuuu9ee33oo54.herokudns.com
2 - is a CNAME record for the domain test.example.com that points to the DNS Target: example-unicorn-990088erd5566e3x1a8p9l3e.herokudns.com

8. Use the dig command to check that your domain is correctly set up. dig +noall +answer example.com will tell you if your domain is pointed at the correct DNS Target.

9. Optional but Recommended Action: Familiarize yourself with the Rules on Adding Domains

Types of domains

The first thing to understand when adding a domain to your Heroku app is that there are different types of domains, and each domain type needs different types of records set in your DNS Provider in order for your domains to work with Heroku.

1. Root domain (sometimes called an Apex Domain) - this is a domain that you buy/register with a DNS Provider and does not have www. or any other "part" or subdomain at the start. Eg:

example.com 
mydomain.com

2. Custom domain with a subdomain - this is a domain that adds extra "parts" known as subdomains onto your root domain, usually with www. or something similar like blog. or store. Eg:

www.example.com
www.mydomain.com
test.example.com
blog.mydomain.com

3. Wildcard Domains - These are used when you want to map any and all subdomains to your app with a single record. Eg: if you create a website that gives each user their own domain: user1.example.com, user2.example.com. To achieve this you would add the wildcard domain *.example.com to your app. For further info see Add A Wildcard Domain in our Devcenter

Types of Records

There are several types of DNS Records which can be set in a DNS Provider's Dashboard/settings panel. However, when setting a domain to work with Heroku there are only 2 types of record that will work.

1. ALIAS, ANAME or FLATTENING Records - These are used with domain type #1 - Root domains. Root domains will only work on Heroku if you have an ALIAS , ANAME or FLATTENING record set in your DNS Provider. Please note: many DNS Providers do not let you set ALIAS, ANAME or FLATTENING records. For further info, please see the Does My DNS Provider allow me to set ANAME, ALIAS or FLATTENING Records section

Note:FLATTENING Records are the exact same thing as ALIAS and ANAME Records, they are just named differently. For example, a very popular DNS Provider Cloudflare uses CNAME FLATTENING which is the same thing as an ALIAS or ANAME Record

2. CNAME Records - CNAME Records are used with domain type #2 - Custom domain with a subdomain. All DNS Providers allow for setting CNAME Records.

Does My DNS Provider allow me to set the ALIAS, ANAME or FLATTENING records?

Many DNS Providers do not allow you to set ALIAS, ANAME or FLATTENING Records, and a Root Domain will only work with Heroku if you have set an ALIAS, ANAME or FLATTENING Record in your DNS Provider.

If your DNS Provider does not allow for ALIAS, ANAME or FLATTENING Records see My root domain isn’t working, what’s wrong? for alternative solutions.

The following are DNS Providers we recommend that do allow for setting ALIAS ANAME or FLATTENING records.

DNSimple
DNS Made Easy/Constellix
easyDNS
PointDNS
namecheap
Gandi.net
Cloudflare - Note: Cloudflare use CNAME Flattening. This is the same thing as an ALIAS or ANAME record

The following is a list of common DNS Providers that do not support ALIAS, ANAME or FLATTENING Records. (There are many more DNS Providers that do not support ALIAS, ANAME or FLATTENING Records who are not on this list.) Many of these Providers will tell you there is no such thing as ALIAS, ANAME or FLATTENING Records and many of these providers will ask you for an IP Address as a target for your root domain:

GoDaddy,
Hostinger,
Google Domains,
OVH

If your DNS Provider does not allow for ALIAS, ANAME or FLATTENING Records see My root domain isn’t working, what’s wrong? for alternative solutions.