Configure Custom Domains

When you create a Koyeb App, you automatically get a generated subdomain for your App ending with koyeb.app.

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:

1. Create and assign your domain to a Koyeb App
2. Add a new DNS record
3. Validate your domain and TLS configuration

If you need help debugging issues with your domain configuration, consult the troubleshooting section.

Create and assign your domain to a Koyeb App

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: www.example.tld
• 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.

Add a new DNS record

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, example.tld is an apex domain while www.example.tld and koyeb.example.tld would be subdomains.

For a subdomain

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.

For an apex domain

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 example.tld to www.example.tld

Validate your domain and TLS configuration

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.

Troubleshooting

Certificate pending emission

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.

Verify your configuration

Ensure your DNS configuration is correct using the dig command.

For a subdomain

In the case of a subdomain, you can use the following command to verify your configuration. For instance, if your domain is www.example.tld run:

$ 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.