Custom domains

On the Pro plan a site can use the user's own domain, such as www.myapp.com. The user adds one DNS record at their domain provider; heremyapp issues and renews the certificate. The heremyapp link keeps working and leads to the domain. Commands use $API (https://api.heremyapp.com/v1) and $AUTH (the bearer token header) from the shell setup.

Connect a domain

Ask the user which domain to use. A subdomain such as www.myapp.com works with every DNS provider; for a root domain see Root domains.

curl -sS --fail-with-body -X POST "$API/spaces/my-app/domains" -H "$AUTH" \
  -H "content-type: application/json" -d '{"hostname":"www.myapp.com"}'

{"hostname":"www.myapp.com","status":"pending","primary":true,"url":"https://www.myapp.com/",
 "records":[{"type":"CNAME","name":"www.myapp.com","value":"domains.heremyapp.app","when":"always"},
            {"type":"TXT","name":"_cf-custom-hostname.www.myapp.com","value":"5c7d…","when":"moving"}],
 "apex":false,"next_step":"Ask the user to add a CNAME record at their DNS provider: …","docs":"https://heremyapp.com/docs/domains.md"}

• 402 plan_limit: custom domains need Pro (up to 10 per account; Enterprise by contract). Tell the user and give them details.upgrade_url.
• 400 invalid_hostname: the message says what to fix (full name, no wildcard, ASCII/punycode, not a heremyapp domain).
• 409 domain_taken: another heremyapp site uses it. If it is the user's, they remove it there first.

Add the DNS record

Show the user the records and where to add them, in their language:

• Many providers want only the part before the domain in the name field (www), not the full name.
• Remove any existing A, AAAA or CNAME record with the same name first; a CNAME cannot sit next to them.
• On Cloudflare DNS, set the record to DNS only (grey cloud).
• The TXT record ("when":"moving") is only for a domain that already serves another site: add it first, wait until the status is issuing or active, then switch the CNAME. Once the domain is active the TXT record can be removed (responses then list only the CNAME).
• A CAA record that limits certificate authorities can block the certificate; it must allow Let's Encrypt and Google Trust Services, or be removed.

You cannot change the user's DNS yourself unless they explicitly give you access to their DNS provider.

Wait until it is live

curl -sS --fail-with-body "$API/spaces/my-app/domains" -H "$AUTH"

Check every minute; DNS usually takes a few minutes, sometimes up to an hour. next_step says what to do, and site_url is the address the site's pages should use. On a local development server the response has "simulated": true: no DNS is checked and the status turns active by itself, so do not tell the user it is live.

After it is live

• site_url of the space is now https://www.myapp.com/. Build the site from the user's project with that address and deploy it again (patch bump) so og:url, og:image, canonical, hreflang, JSON-LD and sitemap.xml use it; the deploy advice points out the old address. Publishing an older deployment again does not change its addresses. If nothing is published yet, deploy the site for the first time the same way.
• The heremyapp link https://heremyapp.com/ACCOUNT/SPACE keeps working and redirects to the domain, and the former site origin redirects too (except /.well-known/ files). Share the domain from now on.
• Installer download links do not change.
• Report to the user: the domain URL, that the heremyapp link still works, and that it renews automatically.

Root domains

Most DNS providers do not allow a CNAME on the root (myapp.com). If the provider offers CNAME flattening, ALIAS or ANAME (Cloudflare DNS does), connect the root like a subdomain ("apex": true in the response); as a second domain it redirects to the primary one. Otherwise connect www.myapp.com and set the provider's URL forwarding to send myapp.com to it. Domains under .app, .dev and other HTTPS-only endings open only over HTTPS, so the forwarding must support HTTPS, or the root must be connected as a domain here.

A space can have up to three domains: the first is the primary, and the others (for example the root, or an earlier domain) redirect to it.

Remove a domain

curl -sS --fail-with-body -X DELETE "$API/spaces/my-app/domains/www.myapp.com" -H "$AUTH"

The site goes back to its heremyapp address. Tell the user they can delete the CNAME record. Removing the last domain, deleting the space, or deleting the account also removes the domain from heremyapp's certificate setup.

Troubleshooting