Custom domains

On a multisite installation, a website can connect a domain it owns under Settings → Domains. A platform operator sets the feature up under Platform → Custom domains; it is off until it is turned on there.

Set it up (platform operator)#

Platform → Custom domains turns the feature on, chooses which connection methods are offered, sets how long an unverified domain is held and how many failed checks take a domain offline, and picks a provider.

{
  on_demand_tls {
    ask http://127.0.0.1:3000/api/domains/tls-allowed
  }
}

https:// {
  tls {
    on_demand
  }
  reverse_proxy 127.0.0.1:3000
}

Connect a domain (website)#

With nameservers, the website manages its own DNS records once the domain is verified: MX, TXT, A, AAAA, CNAME, CAA, and SRV. The records that serve the website cannot be changed.

Verification and certificates#

• A background job checks pending domains every few minutes, and Check now checks at once. When DNS is right, the hostname is attached to the provider, a certificate is issued, and only then is the domain served.
• A domain that is never verified is released after the number of days the operator sets, so nobody can hold a name they do not own.
• A connected domain is checked again every 6 hours. After the operator's number of failures in a row it is no longer served, and if it was the primary address the platform subdomain becomes primary again.
• Removing a domain detaches only a hostname this installation attached at the CDN.

Primary address#

A connected domain can become the website's primary address, which changes its site URL to https://<domain>. With Send visitors to the custom primary domain on, public pages on the site's other addresses redirect there with a 301. Admin, API, and upload paths stay on the address they were opened on, so the site can still be managed if its domain breaks.

Your own nameservers#

Customers see kiki.bunny.net and coco.bunny.net by default. To show your own (ns1.example.com, ns2.example.com), enter them on the platform page and create glue records at that domain's registrar: the first at 91.200.176.1 / 2400:52e0:fff0::1, the second at 109.104.147.1 / 2400:52e0:fff2::1. Zones created afterwards use those names.

Offer it per plan#

Three limits decide what each website may do. Set them on the website page, or under Platform → Defaults for new websites.

Set Upgrade link to send a website to your pricing page when it reaches its domain limit. Turning a limit off later does not disconnect domains that are already connected.

Hooks#

Plugins with platform:tenancy can refuse a domain with the domain.beforeAdd gate and react to the domain.added, domain.activated, domain.failed, and domain.removed actions, for example to charge when a domain goes live. A subscription plugin can lower the domain limits per plan with the quota.effectiveLimit filter or ctx.quotas.set.

ctx.hooks.gate("domain.beforeAdd", (event) => {
  // { siteId, hostname, mode: "records" | "nameservers" }
  if (event.hostname.endsWith(".gov")) event.cancel("Government domains need a manual review.");
});