Learn how to use custom domains with Koyeb Apps
When you create a Koyeb App, you automatically get a generated sub-domain for your App ending with
In addition to this domain, you can reach your Koyeb Apps using your own custom domain. By using your custom domains on Koyeb, you benefit from all the native features offered by the platform including automatic TLS as well as native global load-balancing and caching.
This document explains how to configure a custom domain for your Koyeb App.
Before getting started, to configure a custom domain on Koyeb you need to own a domain and be able to manage the DNS records.
The configuration of a custom domain is a 3-step process you can perform using the Koyeb control panel or CLI:
Go to the Koyeb control panel and click on the Domains tab. You land on the Domains configuration page where you can manage your domains.
On the page, in the Add domain section:
Once ready to create your first domain, click the Add domain button.
Your domain appears on the Domains list and indicates the record to create on to your DNS provider to complete your domain configuration.
With your domain created, the next step is to add a new DNS record to point your domain to Koyeb. Depending on the type of domain you created: Apex or subdomain, the DNS record to add will be different.
To know if you are manipulating an apex domain or a sub-domain, below is a short and simple explanation to know the difference:
A sub-domain is a domain that is part of a larger domain. For instance if your domain is
example.tld is an apex domain and
koyeb.example.tld are subdomains.
If you previously added a sub-domain, you will need to add a
CNAME record to your DNS provider.
The record configuration will be detailed in the Koyeb control panel or CLI and looks like below:
Make sure to replace the Name and Value with your own.
Note that you can add a wildcard record on your DNS provider to avoid having to create a new
CNAME record each time you add a sub-domain on Koyeb.
If the domain you added is an apex domain, you will first need to make sure your DNS provider support adding entries of type
ALIAS are pseudo-records that work like a
CNAME record but can be used safely at the zone apex because it always resolves to A (or AAAA) record(s).
Generally, the most modern DNS providers support ALIAS or ANAME record types, such as:
As for a sub-domain the record configuration will be detailed in the Koyeb control panel or CLI and looks like below:
Once your domain is configured, you can click the Refresh button to validate your domain and TLS configuration.
If everything is correct, your domain status will pass to Active and you will be able to reach your Koyeb App using it.
Note that TLS certificates are automatically provisioned for all domains by default with no additional actions from your side.
Some DNS providers automatically set CAA records which might trigger a
caa_error on our side if they are not correctly configured.
If you are facing a
caa_error try to add the following additional CAA records to allow our certifications authorities to generate TLS certificates automatically.
Ensure your DNS configuration is correct using the
In the case of a sub-domain, you can use the following command to verify your configuration. For instance, if your domain is
$ dig www.example.tld CNAME +noall +answer ; <<>> DiG 9.10.6 <<>> www.example.tld CNAME +noall +answer ;; global options: +cmd www.example.tld. 3600 IN CNAME your-org-uuid.cname.koyeb.app.
If nothing appears, this is generally that your DNS configuration is not valid or propagated yet.
In the case of an apex domain, you can use the following command to verify your configuration. For instance, if your domain is
❯ dig example.tld A ; <<>> DiG 9.10.6 <<>> example.tld A +noall +answer ;; global options: +cmd example.tld. 300 IN A 18.104.22.168 example.tld. 300 IN A 22.214.171.124 example.tld. 300 IN A 126.96.36.199
If nothing appears, this typically indicates that your DNS configuration is not valid or has not yet propagated.