Custom Domain Names for Apps
Last updated 11 July 2015
Table of Contents
By default, any app on Heroku is accessible via its Heroku Domain, which has the form
[name of app].herokuapp.com. For example, you would access an app named ‘serene-example-4269’ with
serene-example-4269.herokuapp.com. To make an app accessible via one or more non-Heroku domain names (for example,
www.yourcustomdomain.com), you must add custom domain(s) to your application as described below.
- Confirm that you own the custom domain name. If not, you can buy one with a domain registration service.
- Add the custom domain to your app with the
heroku domains:addcommand. See below for different variations.
- Look up the Heroku-supplied DNS Target for the custom domain using the
heroku domainscommand as described below.
- Configure your app’s DNS provider to point to the Heroku-supplied DNS Target.
- Test that your app is accessible via the custom domain. There may be a delay while DNS changes propagate.
Domains can be added to both free and paid Heroku apps and adding domains does not incur extra charges. For verification purposes, you must verify your Heroku account to add domains to apps.
Domains can be inspected and managed using either the CLI or Dashboard. To manage domains for an app in Dashboard, go to its “Settings” tab.
Heroku provides neither domain registration service (for registering a custom domain name) nor DNS provider service (for hosting the DNS servers that point your custom domain name at your app).
domain or domain name: full name used to access an app (in words, not with an IP address). For example,
- 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 your 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.
View existing domains
domains command in the Heroku CLI 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 --------------- -------------------------- www.example.com example.herokuapp.com ssl.example.com example-2121.herokussl.com
The DNS Target can be different from the Heroku Domain and different for each custom domain. Also, adding an SSL endpoint to an application may change the supplied DNS Target. If you are planning to secure your application with SSL, first configure SSL to avoid reconfiguring DNS.
Add a custom domain with a subdomain
To add a custom domain with a subdomain, use the
domains:add command in the Heroku CLI:
$ heroku domains:add www.example.com Adding www.example.com to example... done ! Configure your app's DNS provider to point to the DNS Target example.herokuapp.com ! For help, see https://devcenter.heroku.com/articles/custom-domains
See the Rules on adding custom domains section if you receive the error message
example.com is currently in use by another app.
Configuring DNS for subdomains
After using the
domains:add command you must point your DNS provider at the domain’s DNS Target supplied by Heroku. See above for viewing domains to find the DNS Target. This usually takes the form of configuring a new CNAME record with your DNS provider as shown in the table below. Consult with your DNS provider for specific instructions to create CNAME records.
. on the target domain may or may not be required, depending on your DNS provider.
You can confirm that your DNS is configured correctly by using the
host command, assuming your DNS changes have propagated:
$ host www.example.com www.example.com is an alias for example.herokuapp.com. ...
DNS changes can take several minutes to 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 will always remain active, even if you’ve 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
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... done ! Configure your app's DNS provider to point to the DNS Target example.herokuapp.com ! For help, see https://devcenter.heroku.com/articles/custom-domains
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
- Alias record at Zerigo
- CNAME at CloudFlare (Detailed guide, check out the “Root domains” section)
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.
Configuring DNS for root domains if your DNS provider does not support ALIAS/ANAMES/CNAMES for root domains
If your DNS provider does not support ALIAS or ANAMEs, you will need to use subdomain redirection (also called a forward) for configuring DNS for a root domain (you cannot use an A record, which requires an IP address). Subdomain redirection results in a 301 permanent redirect to the specified subdomain for all root domain requests. However, be aware that, using this method, a secure request to the root domain, e.g.,
https://example.com, will result in an error or warning being displayed to the user or the connection may be refused altogether.
Establish a subdomain redirection/forward from the root domain to the
If not already configured, the
www subdomain should then be a CNAME record reference to
Users of AWS’s Route 53 DNS should follow these instructions to establish proper root domain redirection.
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... done
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 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
example.herokuapp.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... done
If you destroy the app, any custom domains assigned to it will be freed. You can subsequently assign them to other apps.
Rules on adding domains
Any user on Heroku can attempt to add any domain to their app. Instead of explicitly verifying domain ownership, Heroku enforces these rules to ensure that domains claimed by one user aren’t used by other users on different apps:
- A single application can have any number of domains assigned to it.
- You can only add a domain to one app. For example if
www.example.comis added to app
example-1you can’t also add it to app
example-2. One app, however, can have multiple domains assigned.
- You can add a wildcard domain if you own all
existing apps already using a corresponding subdomain. For example if
an app is already using
www.example.comyou must own it to add
- You can add a subdomain or apex domain if you own the app assigned
the corresponding wildcard domain. For example to add
example.comyou must own the app with
*.example.com, if such a custom domain exists.
If you’re unable to add a domain that you own, please file a support ticket.