Skip to the page
KilbyDocs
Build and run View as Markdown
On this page

Custom domains

A web service always answers at its Kilby address. You can also serve it on a domain you own, such as api.example.com or example.com, with an HTTPS certificate that Kilby issues and renews for you. Only web services can have custom domains.

A service can have up to 5 custom domains, and a workspace up to 20.

Add a domain#

  1. Open the web service and its Domains tab.
  2. Enter the domain under Add a custom domain and click Add domain. Enter just the name, without https://, a path or a port. Wildcard domains such as *.example.com are not supported yet: add each host on its own.
  3. The tab lists the DNS records to create. Create them at your DNS provider (see below).
  4. Wait. Kilby checks your DNS on its own, and the badge moves through Pending DNS, Verifying, Issuing certificate and Active. Click Verify now to check straight away.

Is the domain already serving a site on another host? Read Moving a site that is live elsewhere first.

The DNS records#

Every domain needs two records, and the tab offers a third one for a site that is moving to Kilby (see the next section).

1. A record that sends visitors to Kilby.

  • A subdomain such as api.example.com: a CNAME record pointing to the service's Kilby address (my-api-x7k2.apps.kilby.neuramorphic.ai). The Domains tab shows the exact value to copy.
  • An apex (root) domain such as example.com: a CNAME is not allowed there, so use an ALIAS or ANAME record (also called CNAME flattening) pointing to the Kilby address if your DNS provider has one. It keeps working if Kilby's addresses change. Otherwise create the A records the tab lists. They are the load balancer's current addresses, so look at the tab again if the site stops answering.

2. A TXT record that proves you own the domain.

TypeNameValue
TXT_kilby-challenge.<your host>kilby-verify=<token>

For api.example.com the name is _kilby-challenge.api.example.com, which most DNS providers want written relative to your zone (_kilby-challenge.api). The token is different for every domain and is shown in the tab. You can delete the TXT record once the domain is Active.

Remove any AAAA (IPv6) record for the host that does not point to Kilby: visitors and Let's Encrypt try IPv6 first, so a leftover one breaks the domain. If your domain has CAA records that restrict who may issue certificates, one of them must allow letsencrypt.org.

Steps for your DNS provider#

While a domain still needs records, the Domains tab looks up who serves its DNS, from the domain's name servers, and shows the steps for that provider with the domain's own values: where its panel adds records, how it wants the names written, and its known pitfalls. Kilby has steps for Cloudflare, Amazon Route 53, GoDaddy, Namecheap, Google Cloud DNS, Squarespace, Hostinger, DigitalOcean, Vercel, Netlify DNS or NS1, Wix and IONOS. For any other provider, the tab shows steps that work anywhere.

  • Cloudflare: set Proxy status to DNS only on Kilby's records. Cloudflare answers a proxied record with its own addresses, so Kilby would not find the record and could not issue the certificate.
  • Amazon Route 53: for the root of the domain, leave the record name empty (Route 53 does not take @ there), and put several values of one record on separate lines of the same record.

Moving a site that is live elsewhere#

If the domain already serves a site on another host, get its certificate before you switch: then HTTPS works from the first visitor that reaches Kilby. Otherwise the certificate can only be requested after the switch, and for those minutes visitors get a certificate error. A site that sends HSTS is refused outright by browsers during that time, with no way past the warning.

  1. Add the domain. Leave the records that send visitors to your site (its CNAME, or its A records) pointing to the old host for now.
  2. Create only one record at your DNS provider: a CNAME named _acme-challenge.<your host> pointing to <token>.acme.kilby.neuramorphic.ai. For api.example.com the name is _acme-challenge.api.example.com and the value looks like k3x9d2f7q8m1v5n0b4c6z2w8.acme.kilby.neuramorphic.ai; the tab shows the exact value. This record also proves you own the domain, so the TXT record is not needed. If the name already has records (a TXT left by another provider, for example), delete them first: a CNAME cannot share its name with other records.
  3. Kilby verifies the record, gets the certificate from Let's Encrypt through it (a DNS-01 challenge: Let's Encrypt follows your CNAME into Kilby's zone, where Kilby writes the answer) and turns HTTPS on for the domain. The badge says Ready to switch.
  4. When you are ready, point those records to Kilby, as the tab shows them (Switch when ready). Visitors move over as their DNS caches expire, so lower the records' TTL a day before if you can. Kilby looks for the switch every 2 minutes during the first hour after the domain was verified, then every 10 minutes, and the badge turns Active when it sees it. Click Verify now to look straight away.

Keep the _acme-challenge record: the certificate is renewed through it. Kilby looks at it every 60 minutes. If it is gone and the domain points to Kilby, the certificate is renewed by calling the domain itself from then on (HTTP-01), and the current one is served until the new one is issued. If it is gone and the domain does not point to Kilby yet, the tab says so: put it back.

Redirect one domain to another#

A domain can send its visitors to another domain of the same service, with a 301 that keeps the path and the query string: for example www.example.com to example.com, or the other way round.

  1. Add both domains to the service.
  2. On the domain that should redirect, choose Visitors: Are redirected to example.com and click Save.

The redirecting domain keeps its own certificate, so https://www.example.com/cart answers and redirects to https://example.com/cart. Plain http://www.example.com goes to https://www.example.com first, then to the other domain. The redirect is answered by Kilby's gateway: your service does not see those requests.

One hop at most: a domain that redirects cannot be the target of another, and a domain that others redirect to cannot redirect. A domain that another one redirects to cannot be removed until that one serves the service again or is removed. Changing a redirect does not restart the service.

The primary address#

Every web service has a primary address: the one its header and Open use in the dashboard, and the API reports as primary_domain. It is the service's Kilby address, or one of its custom domains that is live: active, serving the service (not redirecting) and pointing to Kilby.

  • Until you choose, the first custom domain to go live is primary, and the Domains tab says so. Before that, the Kilby address is.
  • To choose, click Make primary on a live custom domain, or on the Kilby address to go back to it. The choice stays until you change it. With the API: PATCH /api/v1/services/<id>/primary-domain with {"primary_domain": "example.com"}, or null to let Kilby pick the first custom domain to go live again.
  • A chosen domain that stops being live (removed, set to redirect, without a valid certificate, or no longer pointing to Kilby) is never shown as the primary address: the header uses the Kilby address, and the Domains tab says why. When the domain is live again, it is primary again.
  • Kilby looks again at every domain that points to it every 60 minutes. One that points somewhere else is marked Points elsewhere and stops being primary until it points here again.
  • The Kilby address always works. While a custom domain is primary, the header keeps it in sight ("also at ...").

Choosing the primary address deploys nothing and restarts nothing. The variables Kilby sets do not change: KILBY_EXTERNAL_HOSTNAME, and RENDER_EXTERNAL_HOSTNAME with Render compatibility, stay the Kilby address, and so does the API's url. An application that builds its allowed hosts from those variables keeps accepting the Kilby address; add your custom domains to its allowed hosts yourself.

How long it takes#

Kilby looks up your records in public DNS every 2 minutes during the first hour after you add the domain (or click Verify now), then every hour, and stops after 7 days. If it stopped, fix the records and click Verify now. A change at your DNS provider can take from a few minutes up to the time to live (TTL) of the old record to show up. Once the records are right, the certificate usually follows within a few minutes.

The certificate#

When the records are verified, Kilby requests a certificate from Let's Encrypt for the host. Without the _acme-challenge record, Let's Encrypt calls http://<your host>/.well-known/acme-challenge/... to check it (an HTTP-01 challenge), so the host must already point to Kilby. With it, Let's Encrypt checks the record instead (DNS-01), and the host may still point elsewhere. The certificate is renewed automatically, and the tab shows when the current one is valid until. After it is issued, HTTPS is switched on, and plain http:// requests to the domain are redirected to HTTPS with a 301.

If a certificate cannot be renewed, the domain shows an error: The certificate is no longer valid and could not be renewed. Check that the DNS records still point to Kilby.

Messages and what to do#

These are the messages the Domains tab shows while the records are not right. The host names and addresses are examples.

SituationMessageWhat to do
TXT record missingAdd a TXT record named _kilby-challenge.api.example.com with the value kilby-verify=k3x9d2f7q8m1v5n0b4c6z2w8.Create the TXT record.
TXT record has another tokenThe TXT record _kilby-challenge.api.example.com is kilby-verify=an-older-token, expected kilby-verify=k3x9d2f7q8m1v5n0b4c6z2w8.Replace its value with the one in the tab.
No CNAME yetapi.example.com has no DNS records yet. Add a CNAME record pointing to my-api-x7k2.apps.example.net.Create the CNAME record.
CNAME points elsewhereapi.example.com is a CNAME to other.example.org, expected a CNAME to my-api-x7k2.apps.example.net.Point it to the Kilby address.
An A record points elsewhereapi.example.com points to 198.51.100.7, expected a CNAME to my-api-x7k2.apps.example.net.Replace it with the CNAME, or remove it.
An AAAA record points elsewhereapi.example.com also has an AAAA (IPv6) record for 2001:db8::1, which is not a Kilby address. Remove it.Remove the AAAA record.
Apex with no A recordexample.com has no A record yet. Add A records for 203.0.113.10 and 203.0.113.11, or an ALIAS/ANAME record to my-api-x7k2.apps.example.net.Create an ALIAS or ANAME record, or the A records.
CAA blocks Let's EncryptThe CAA records of example.com allow only digicert.com to issue certificates. Add a CAA record on example.com: 0 issue "letsencrypt.org".Add the CAA record it names.
Stopped checkingWe stopped checking after 7 days without the right DNS records. Fix the records below and click Verify now.Fix the records and click Verify now.
A domain that pointed here points elsewhereapi.example.com no longer points to Kilby, so visitors who type it do not reach this service. api.example.com is a CNAME to old-host.example.org, expected a CNAME to my-api-x7k2.apps.example.net.Point it to Kilby again, or remove it.
Points elsewhere, no _acme-challenge recordMoving a site that is live elsewhere? Add a CNAME record named _acme-challenge.api.example.com pointing to k3x9d2f7q8m1v5n0b4c6z2w8.acme.kilby.neuramorphic.ai instead: the certificate is issued before you switch.Create that record, or point the domain to Kilby.
_acme-challenge has another value_acme-challenge.api.example.com is a CNAME to an-older-token.acme.kilby.neuramorphic.ai, expected k3x9d2f7q8m1v5n0b4c6z2w8.acme.kilby.neuramorphic.ai.Replace its value with the one in the tab.
_acme-challenge removed before the switch_acme-challenge.api.example.com no longer points to k3x9d2f7q8m1v5n0b4c6z2w8.acme.kilby.neuramorphic.ai, and api.example.com does not point to Kilby either, so its certificate cannot be renewed. Put the record back.Create the record again.

Other messages you may see:

  • "<host> is already in use by another service on Kilby." Another workspace verified that host first.
  • "<host> is already added to a service in this workspace." Remove it from the other service first.
  • "<host> and its subdomains belong to the platform and cannot be used as a custom domain." Kilby's own domains cannot be used.
  • "Let's Encrypt did not issue a certificate: ..." Let's Encrypt refused the order, and the message says why. Kilby retries on its own. Once the cause is fixed, click Verify now to retry at once.
  • "A service can have up to N custom domains." and "A workspace can have up to N custom domains." You reached a limit. Remove a domain to add another.

A suspended service keeps its domains and certificates, but visitors get an error until it is resumed. Removing a domain stops it serving the service right away and removes its certificate.

With the API#

sh
curl -sS -X POST https://onkilby.com/api/v1/services/<id>/domains \
  -H "Authorization: Bearer $KILBY_API_KEY" -H "Content-Type: application/json" \
  -d '{"hostname": "api.example.com"}'

The answer lists the DNS records to create; each one has a purpose: route, ownership or certificate. POST /api/v1/domains/<id>/verify is Verify now, PATCH /api/v1/domains/<id> with {"redirect_to": "example.com"} sets a redirect (null removes it), and DELETE /api/v1/domains/<id> removes the domain. An active domain whose routed_at is null has its certificate but does not point to Kilby yet. The fields are in the API reference.