Key takeaways
- An app on Pro or Scale can answer at your own domain: add it on Settings → Domains, add the CNAME it lists, and the certificate is issued and renewed for you.
- A bare domain can't hold a CNAME, so it works only where its DNS flattens one at the root in a way that can be verified. Elsewhere, use www and redirect the bare domain to it.
- CAA records allow only the certificate authorities they name. Certificates come from Let's Encrypt, Google Trust Services or SSL.com, and the authority can change at renewal, so a domain with CAA records must allow all three.
- Apps looks up a domain's CAA records when it's added and at every check, lists the CAA records it's missing, and marks the domain Needs attention when they block its certificate.
Most of the time, putting an app on your own domain takes one DNS record. You add app.example.com, point a CNAME at us, and a few minutes later it serves over HTTPS. The cases that take longer are nearly always one of two things: the domain is a bare domain, or it has a CAA record that doesn't allow the authority issuing the certificate. This article covers both, and how Apps reports them.
Adding a domain
On an app's Settings → Domains, choose Add a domain. Production's page adds domains for production; a development environment's adds them for that environment, served by its dev server with hot reload, for testing what needs your own domain, such as cookies on a shared parent domain. From a terminal:
ib-apps domains add app.example.com
ib-apps domains check app.example.com # look again now instead of waiting for the hourly check
The page then lists every DNS record to add at your DNS provider, each marked Required or Optional with what it's for. We don't manage your DNS, so this list is the whole job:
| Type | Name | Value | When |
|---|---|---|---|
| CNAME | app.example.com | cname.inferencebureau.app | Always |
| CAA | example.com | 0 issue "ssl.com" (one per missing authority) | Only when the domain's CAA records leave an authority out |
| TXT | shown per domain | shown per domain | Optional: verifies the domain before you move the CNAME, if it serves another site today |
If your DNS provider offers its own proxy on the CNAME, turn it off. The domain has to point straight at cname.inferencebureau.app.
Custom domains come with the Pro plan (five across the team's apps) and Scale (25). On Free, adding one is refused with a note saying so. Domains aren't billed separately: their traffic counts toward production's requests and bandwidth like any other.
Bare domains
A bare domain such as example.com is the top of its DNS zone, and DNS doesn't allow a CNAME there, because the zone's own SOA and NS records already sit at that name. Many DNS providers work around this with an ALIAS, ANAME or flattened CNAME record: the provider looks up the target itself and answers with plain addresses.
The trouble is that plain addresses can't be verified. Issuing a certificate for a custom domain starts by confirming the domain really points at us, and an answer made of A records doesn't say where it came from. So Apps checks each domain when it's added. A subdomain is fine anywhere. A bare domain is accepted only when its DNS provider flattens a CNAME at the root in a way that can still be verified, and the Domains docs name the provider that works today. Anywhere else, the domain is refused and the dashboard offers www.example.com instead. Add that, and redirect example.com to it at your DNS provider or registrar. Most offer a redirect.
The same check catches a domain added as a CNAME and later switched to A records. It shows as Needs attention, with the CNAME listed and a note to replace the A, AAAA or ALIAS records with it.
What a CAA record does
A CAA record says which certificate authorities may issue certificates for a domain. example.com CAA 0 issue "letsencrypt.org" means only Let's Encrypt may issue for example.com and every name under it. Before issuing, an authority looks for CAA records at the name, then at each parent in turn, and the first set it finds decides. If no name has any, every authority is allowed, which is why most domains never run into this.
Some DNS providers add CAA records to every domain, and many security checklists recommend them. Either way, a domain can end up allowing one or two authorities without anyone remembering why.
Certificates for custom domains on Apps come from Let's Encrypt, Google Trust Services or SSL.com. We don't choose which one, and it can change at renewal. So a domain that has CAA records must allow all three, or a certificate that issued fine in March can fail to renew in June. The values are:
example.com. CAA 0 issue "letsencrypt.org"
example.com. CAA 0 issue "pki.goog"
example.com. CAA 0 issue "ssl.com"
Two details catch people out. A CAA record for app.example.com can't sit beside its CNAME, since a CNAME can't share its name with other records, so it goes on the parent, example.com. And a bare domain's CAA records go on the domain itself, where they're the first set an authority finds.
How the dashboard reports it
When a domain is added, and each time it's checked, Apps looks up its CAA records the way an authority would: the parent, then the parent's parent, until a name has some. If they leave out any of the three authorities, the page lists a required CAA record for each missing one, on the name where the records were found. If the authority itself reports that CAA blocked it, the record it names is listed too, in case our own lookup couldn't see the records.
Domains show one of three statuses:
- Pending: waiting for the CNAME, or for the certificate once the CNAME is found. The note under the domain says which.
- Active: the domain serves its environment over HTTPS.
- Needs attention: something only you can fix. For CAA, the note reads "example.com's CAA records block the certificate for app.example.com. Add the CAA records listed, then check again."
Pending domains are checked every hour and whenever the Domains page opens. Active ones are checked once a day. Check again asks right away and has the domain's pointing and certificate looked at again, rather than waiting for the next scheduled attempt. Once the records are in place, the certificate is usually issued within a few minutes.
After it's active
Once one of production's domains is active, Make primary redirects browsers that open the app's inferencebureau.app address to the same path on your domain. Webhooks and API calls to the old address are still served there, so nothing that already calls it breaks. At production's next deploy, IB_APP_URL and a Shopify app's URL in the Shopify admin move to the primary domain too. The app sees the custom domain in x-forwarded-host.
Frequently asked questions
Why won't my certificate issue when the CNAME is correct?
Usually a CAA record. If the domain or a parent has CAA records that don't allow letsencrypt.org, pki.goog and ssl.com, the certificate can be blocked. The Domains page lists the CAA records to add and marks the domain Needs attention.
Can I use a bare domain like example.com?
Only when its DNS flattens a CNAME at the root in a way that can be verified; the Domains docs name the provider that works today. Elsewhere, add www.example.com and redirect example.com to it at your DNS provider or registrar.
Where does the CAA record go?
On the parent of the hostname you added, such as example.com for app.example.com, because a CAA record can't sit beside a CNAME. A bare domain's CAA records go on the domain itself.
Which plans include custom domains?
Pro includes five custom domains across the team's apps and Scale includes 25. Free doesn't include any. Domains aren't billed separately.