Table of Contents
All apps on Heroku are accessible via their
herokuapp.com app subdomain. E.g., for an app named
example it’s available at
example.herokuapp.com. To serve traffic on a non-herokuapp.com domain, e.g.,
www.example.com, you need to configure your application with a custom domain (a free feature on Heroku).
The process to add a custom domain to your application can vary slightly, depending on the type of domain(s).
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.
There are several domain configurations available to your app including:
- One or more subdomains like
- A root domain like
- Wildcard domains that match any subdomain, represented as
A single application can have any number of domains assigned to it utilizing one or more of the above domain types. The same basic setup process applies for each domain:
- Tell Heroku which custom domains are specific to your application
- Configure your application’s DNS to point to Heroku
Specific instructions for each configuration are detailed below.
For each custom subdomain you want attached to your app, e.g.,
www.example.com, use the
domains:add command from the Heroku CLI:
See the domain precedence section if you receive the error message
example.com is currently in use by another app.
$ heroku domains:add www.example.com Adding www.example.com to example... done
Next, for each subdomain, configure your DNS with a CNAME record pointing the subdomain to your app’s Heroku
herokuapp.com hostname (shown here resolving
www.example.com to the
. on the target domain may or may not be required, depending on your DNS provider.
You can confirm that your DNS is configured correctly with the
$ host www.example.com www.example.com is an alias for example.herokuapp.com. ...
Output of this command varies by Unix flavor, but should indicate that your hostname is either an alias or CNAME of
If you intend to use a root domain, e.g.,
example.co.uk, you must add it in addition to any custom subdomains.
$ heroku domains:add example.com Adding example.com to example... done
Zone apex domains (aka “naked”, “bare” or “root” domains), e.g.,
example.com, using conventional DNS A-records are not supported on Heroku. However, there are alternative configurations that allow for root domains while still being resilient in a dynamic runtime environment.
CNAME functionality at the apex
Some DNS hosts provide a way to get CNAME-like functionality at the zone apex using a custom record type. Such records include:
For each provider, the setup is similar: point the ALIAS or ANAME entry for your apex domain to example.herokuapp.com, just as you would with a CNAME record.
Depending on the DNS provider, an empty or
@ Name value identifies the zone apex.
If your DNS provider does not support such a record-type, and you are unable to switch to one that does, you will need to use subdomain redirection to send root domain requests to your app on Heroku.
For users without access to a modern DNS configuration, subdomain redirection is a viable alternative. Subdomain redirection results in a 301 permanent redirect to the specified subdomain for all root domain requests.
Almost all DNS providers offer domain redirection services – sometimes also called domain forwarding. 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. If you’re not using SSL, or are only distributing URLs in subdomain SSL form, e.g.,
https://www.example.com, this error won’t affect you.
Establish a redirect/forward from the root domain to the
Users of AWS’s Route 53 DNS should follow these instructions to establish proper root domain redirection.
If not already configured, the
www subdomain should then be a CNAME record reference to
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 the wildcard domain to your app as you do 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 TLD (top level domain) to any of your other apps. Specific subdomains are evaluated before wildcard domains when routing requests.
It’s important to make sure your DNS configuration agrees with the custom domains you’ve added to 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.
* wildcard subdomain notation to add a CNAME record to
example.herokuapp.com with your DNS provider.
After your DNS changes have propagated you will be able to look up and access any subdomain:
$ host any-subdomain.example.com any-subdomain.example.com is an alias for example.herokuapp.com ... $ curl -I http://any-subdomain.example.com/ HTTP/1.1 200 OK ...
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.
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:
- 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.
The herokuapp.com domain
example.herokuapp.com 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
UTF-8 domain names
Domain names that contain accented, or other non-ASCII, characters should be added using punycode. For instance, the
éste.com domain name should be converted to
xn--ste-9la.com when passed to
$ heroku domains:add xn--ste-9la.com