Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Operations and Alternatives

Custom Domains and TLS

Point your own domain at a Heroku app: heroku domains:add, DNS target, CNAME versus ALIAS for apex domains, automated certificate management, redirects and HSTS.

Every Heroku app gets a free address like my-app-1a2b3c4d5e6f.herokuapp.com, which is fine for testing but not for a product. This lesson shows how to attach your own domain, how DNS records must look, how HTTPS certificates are handled, and the traps with root (apex) domains. Heroku and DNS providers cannot be used from this site, so commands are read-only and the DNS checker is a runnable stand-in.

Add the domain to the app

Custom domains need a paid dyno type (not Eco). Add the name in the dashboard under Settings, Domains or with the CLI:

Terminal
heroku domains:add www.example.com --app my-app
heroku domains --app my-app

Heroku answers with a DNS target, a hostname like fancy-grape-abc123.herokudns.com, unique to that domain on that app. Create your DNS record to point at that target, not at the older generic my-app.herokuapp.com name and never at a hard-coded IP address; Heroku's addresses change and are shared.

DNS records

For a subdomain such as www or shop, create a CNAME record:

Type Name Value
CNAME www fancy-grape-abc123.herokudns.com

The apex (also called root or naked) domain, example.com itself, is harder. The DNS standard forbids a CNAME at the same name as other records (like the MX and NS records every apex has). Solutions:

  • ALIAS or ANAME records, offered by many DNS providers: they behave like a CNAME at the apex by resolving the target on their side.
  • CNAME flattening, the same idea under a different name (Cloudflare uses it).
  • Or send the apex to www with a redirect at your DNS or registrar, and put the app on www.

If your DNS provider supports none of these, move DNS to one that does. Do not point apex A records at IPs you looked up.

flowchart LR
    U["Browser"] --> D["DNS lookup<br/>www.example.com"]
    D -->|"CNAME"| T["fancy-grape-abc123<br/>.herokudns.com"]
    T --> R["Heroku router"]
    R --> A["Your dynos"]

The CNAME hands the name over to Heroku's DNS target, so Heroku can change addresses without you noticing.

HTTPS certificates

Heroku offers Automated Certificate Management (ACM) for apps on paid dynos: it requests a free certificate from Let's Encrypt for your domains, verifies ownership through the DNS target, and renews it before expiry.

Terminal
heroku certs:auto:enable --app my-app
heroku certs:auto --app my-app

Certificates may take a little while to appear after the DNS record works; certs:auto shows the status. If you need a certificate you buy yourself (for example an organization-validated or wildcard certificate), you can upload it with heroku certs:add, but you must renew it by hand, and an expired certificate shows browser warnings to every visitor.

Heroku serves certificates with SNI (Server Name Indication), which all modern browsers support.

Redirects and canonical hostnames

Decide on one canonical address (https://www.example.com or https://example.com) and redirect the others to it: from http to https, and from the alternative hostname to the canonical one. Search engines prefer one address, and cookies are per hostname. Heroku's router does not redirect for you, so do it in the app or at your DNS/CDN layer:

  • Behind the router, your app sees plain HTTP and the original protocol in the X-Forwarded-Proto header. Most frameworks have a setting to trust it (Django SECURE_PROXY_SSL_HEADER, Rails config.force_ssl, Express app.set("trust proxy", 1)).
  • Add an HSTS header (Strict-Transport-Security) once HTTPS works everywhere, so browsers refuse plain HTTP in future. Start with a short max-age while testing, because a mistake is cached by browsers.
Python Stand-in: compute the canonical redirect

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three of the four requests are redirected to https://www.example.com/..., and the one that already matches is served. This is the logic you would put in a middleware.

Checking DNS

Typical problems after setting records: a typo in the target, a record that still points at an old host, a CAA record that blocks Let's Encrypt, or caching (TTL, the time resolvers keep old answers). Tools you can run yourself: dig www.example.com CNAME, nslookup, or a web DNS checker.

Python Stand-in: validate a DNS setup

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

It flags the A record and the apex CNAME that conflicts with the A and MX records. A provider ALIAS record would solve the second problem.

Wildcards

heroku domains:add "*.example.com" attaches a wildcard so every subdomain reaches the same app (useful for multi-tenant products with a subdomain per customer). Wildcard certificates with ACM are supported on paid dynos; check the current docs. Remember to also allow the subdomains in your app's host-header validation.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should a CNAME for www.example.com point to?

    Each domain gets a unique DNS target; pointing at it lets Heroku change addresses safely.
  2. 2. Why can't you use a normal CNAME for the root domain?

    The apex carries NS and MX records, so use ALIAS/ANAME/CNAME flattening or redirect to www.
  3. 3. What does Automated Certificate Management do?

    ACM obtains a Let's Encrypt certificate and renews it automatically.
  4. 4. Which header tells your app the original protocol?

    The router terminates TLS and passes the original scheme in X-Forwarded-Proto.

Summary

  • Add the domain with heroku domains:add, then CNAME to the DNS target (ALIAS/ANAME at the apex).
  • ACM gives free, renewing certificates on paid dynos; manual certificates need manual renewal.
  • Pick one canonical host, redirect http to https, trust X-Forwarded-Proto, then add HSTS.
  • Debug with dig and watch for CAA records and DNS caching.

Next: Troubleshooting Heroku Errors