Custom Domain Names for Apps
Last updated September 03, 2020
Table of Contents
By default, a Heroku app is available at its Heroku domain, which has the form
[name of app].herokuapp.com. For example, an app named
serene-example-4269 is hosted at
Heroku DNS uses DNSSEC to authenticate requests to all
herokudns.com domains. DNSSEC is a security system that gives DNS servers the ability to verify that the information they receive is reliable.
To make your app available at a non-Heroku domain (for example,
www.yourcustomdomain.com), you add a custom domain to it.
You can add custom domains to any Heroku app. Adding domains does not incur extra charges. For security purposes, you must verify your Heroku account to add domains to apps.
Heroku does not provide a domain registration service (for registering a custom domain name) or a DNS provider service (for hosting the DNS servers that point your custom domain name to your app).
Summary of steps
The remainder of this article covers these steps in greater detail:
- Confirm that you own the custom domain name. You can buy a custom domain name with a domain registration service.
- Add the custom domain to your app with the
- Look up the Heroku-supplied DNS target for the custom domain using the
- Configure your app’s DNS provider to point to the Heroku-supplied DNS target.
- Confirm that your app is accessible via the custom domain. There might be a delay while DNS changes propagate.
Add a custom domain with a subdomain
To add a custom domain with a subdomain, use the
domains:add Heroku CLI command:
$ heroku domains:add www.example.com Adding www.example.com to ⬢ example-app... done ▸ Configure your app's DNS provider to point to the DNS Target ▸ whispering-willow-5678.herokudns.com. ▸ For help, see https://devcenter.heroku.com/articles/custom-domains The domain www.example.com has been enqueued for addition ▸ Run heroku domains:wait 'www.example.com' to wait for completion
See the Rules on adding domains section if you receive the error message
example.com is currently in use by another app.
Configuring DNS for subdomains
After you add a domain with the
heroku domains:add command, you need to point your DNS provider at the DNS target provided by Heroku. You can view this DNS target with the
heroku domains command (see View existing domains for details).
You usually configure a new
CNAME record with your DNS provider to point it at Heroku. The following table shows common
CNAME record patterns:
. on the target domain may or may not be required, depending on your DNS provider.
Consult your DNS provider’s documentation for specific instructions on creating
You can confirm that your DNS is configured correctly with the
host command, assuming your DNS changes have propagated:
$ host www.example.com www.example.com is an alias for whispering-willow-5678.herokudns.com. ...
DNS changes can take between several minutes and several days to take effect. Lowering your DNS TTL ahead of time can minimize, but not eliminate, this propagation time.
Your app’s Heroku domain always remains active, even if you set up a custom domain. If you want users to use the custom domain exclusively, your app should send HTTP status 301 Moved Permanently to tell web browsers to use the custom domain. The
Host HTTP request header field will show which domain the user is trying to access; send a redirect if that field is
Keep in mind that you have to maintain your DNS records in sync with your Heroku resources. If you decide to remove a Heroku app but do not remove or update your corresponding DNS record, you become vulnerable to Subdomain Takeover attacks.
Add a custom root domain
Root domains must be added in addition to any subdomains. The process for adding root domains is the same in the Heroku CLI:
$ heroku domains:add example.com Adding example.com to ⬢ example-app... done ▸ Configure your app's DNS provider to point to the DNS Target ▸ whispering-willow-5678.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
Configuring DNS for root domains
Configuring your DNS provider for a root domain is similar to configuring a DNS provider for a subdomain. However, whereas with subdomains the type of record to configure is always a CNAME, with root domains the type of record depends on the DNS provider:
- ALIAS at DNSimple
- ANAME at DNS Made Easy
- ANAME at easyDNS
- ALIAS at PointDNS
- CNAME at CloudFlare. Also see the CloudFlare guide on SSL on Heroku.
- ALIAS at namecheap
Some DNS providers will only offer A records for root domains. Unfortunately, A records will not suffice for pointing your root domains to Heroku because they require a static IP. These records have serious availability implications when used in environments such as on-premise data-centers, cloud infrastructure services, and platforms like Heroku. Since Heroku uses dynamic IP addresses, it’s necessary to use a CNAME-like record (often referred to as ALIAS or ANAME records) so that you can point your root domain to another domain. See examples below.
Whichever provider you have, point the ALIAS/ANAME/CNAME entry for your root domain to the DNS Target, just as you would with a CNAME record:
Depending on the DNS provider, an empty or
@ Name value identifies the root domain.
Add a wildcard domain
Wildcard domains allow you to map any and all subdomains to your app with a single record. A common use of a wildcard domain is with applications that use a personalized subdomain for each user or account. You can add a wildcard domain if you own all existing apps already using the same top-level domain (TLD). For example, if an app is already using
www.example.com, you must own it to add
Add a wildcard domain to your app as you would with any other domain, but use the
* wildcard subdomain notation.
$ heroku domains:add *.example.com Adding *.example.com to ⬢ example-app... done ▸ Configure your app's DNS provider to point to the DNS Target ▸ encircled-magnolia-9265.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
If one of your apps has a wildcard domain, you can still add specific subdomains of the same top-level domain (TLD) to any of your other apps. Specific subdomains are evaluated before wildcard domains when routing requests.
With wildcard domains it’s important to make sure your DNS provider configuration agrees with Heroku. In particular, if you have configured your DNS for
*.example.com to point to
example.herokuapp.com, be sure you also run
heroku domains:add *.example.com. Otherwise, a malicious person could add
baddomain.example.com to their Heroku app and receive traffic intended for your application.
Configuring DNS for wildcard domains
* wildcard subdomain notation to add a CNAME record to
encircled-magnolia-9265.herokudns.com. with your DNS provider.
Remove a custom domain
Remove a domain with
$ heroku domains:remove www.example.com Removing www.example.com from ⬢ example-app... done
If you destroy the app, any custom domains assigned to it will be freed. You can subsequently assign them to other apps.
View existing domains
heroku domains command to view an app’s current Heroku domain, custom domains, and DNS targets:
$ heroku domains === example Heroku Domain example.herokuapp.com === example Custom Domains Domain Name DNS Target --------------- -------------------------- example.com hidden-sierra-7936.herokudns.com www.example.com whispering-willow-5678.herokudns.com
For older applications, the DNS Target may be of the form
[name of app].herokuapp.com. If you are not using SSL, both
[name of app].herokuapp.com and
<haiku>.herokudns.com formats will work as DNS Targets, regardless of the DNS Targets shown in Dashboard and CLI output.
Common Runtime - SSL Endpoint
If you’re using the SSL Endpoint, note that your DNS Targets will be a little different. For apps in the Common Runtime, the endpoint domain name will have a name in the form of
The DNS Target format for Private Space apps is
Rules on adding domains
Any Heroku user can attempt to add any domain to their app. Instead of explicitly verifying domain ownership, Heroku enforces the following rules to ensure that domains aren’t claimed by multiple users or apps:
- A single app can have up to 1,000 custom domains assigned to it.
- A given domain can be added to only a single Heroku app. For example, if you add
example-1, you can’t also add it to app
- You can add a wildcard domain if you own all
existing apps that already use a corresponding subdomain. For example, if
an app is already using
www.example.com, you must own it in order to add
- You can add a subdomain or apex domain if you own the app that is assigned
the corresponding wildcard domain. For example, to add
example.com, you must own the app with
*.example.com(if such a custom domain exists).
- You can add a subdomain if all applications using wildcard SSL certificates for that domain are owned by the same account. For example, if another account has an app with a
*.example.comwildcard SSL certificate uploaded, you can’t add
something.example.comto an app on your account.
wildcardis a reserved Heroku subdomain keyword. For example,
If you’re unable to add a domain that you own, please file a support ticket.
Domain name glossary
- Domain or domain name: full name used to access an app (in words, not with an IP address). For example,
- Subdomain: the
- Root domain (or naked, bare, or zone apex domain): the ‘yourcustomdomain.com’ in ‘www.yourcustomdomain.com’
- Wildcard domain: domains that match any subdomain, represented as
- Domain registration service: company that lets you buy and register a custom domain name
- DNS provider: company that maintains the DNS servers that translate a custom domain name to a destination (‘DNS Target’). The fields are often called CNAME, ALIAS, ANAME, or A records. Only the first three work with Heroku apps, as A records require an IP address and Heroku apps do not have stable inbound IP addresses.
- Heroku Domain: Heroku term for default domain given to each app. Has the form
[name of app].herokuapp.com
- DNS target: Heroku term for the Heroku domain to give to a DNS provider (e.g., in a CNAME record) to be the destination for a custom domain name.