Configure Custom Domains
When you create a Koyeb App, you automatically get a generated subdomain 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 of 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:
- Create and assign your domain to a Koyeb App
- Add a new DNS record
- Validate your domain and TLS configuration
If you need help debugging issues with your domain configuration, consult the troubleshooting section.
Go to the Koyeb control panel (opens in a new tab) 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:
- Fill in the domain name field with the domain you want to assign to your Koyeb App, for instance:
- Select the Koyeb App you want to assign the domain to
Once ready to create your first domain, click the Add domain button.
Your domain appears in the Domains list and shows the record to create with to your DNS provider to complete your domain configuration.
With your domain added, the next step is to create 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.
A subdomain is a domain that is part of a larger domain. For example, if your domain is
example.tld is an apex domain while
koyeb.example.tld would be subdomains.
You will need to add a
CNAME record to your DNS provider.
The record configuration will be displayed in the Koyeb control panel or CLI and will look similar to this:
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 subdomain on Koyeb.
Koyeb does not support directly setting apex domains for most DNS providers. Fortunately, most DNS providers support setting up HTTP redirections. Follow these steps to set up redirection:
- Add a new subdomain on Koyeb, for example
www.example.tld, as detailed in the previous section
- Add an HTTP redirection on your DNS provider, for example from
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.
The validation of your domain generally takes under five minutes. In exceptional cases, it may take up to four hours.
Some DNS providers automatically set CAA records which might prevent us from emitting a certificate for you if they are not correctly configured. If your
CNAME record is correct but your certificate is not emitted, 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 subdomain, 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 generally indicates that your DNS configuration is not valid or propagated yet.