Announcing US-East 🇺🇸 region: Deploy your apps in Washington, DC

Configure custom domains

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

Create and assign your domain to a Koyeb App

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:

  • 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 on the Domains list and indicates the record to create on to your DNS provider to complete your domain configuration.

Add a new DNS record

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

For a sub-domain

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:

NameTypeValue
wwwCNAMEyour-org-uuid.cname.koyeb.app

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.

For an apex domain

If the domain you added is an apex domain, you will first need to make sure your DNS provider support adding entries of type ANAME or ALIAS. ANAME and 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:

  • DNS Made Easy
  • DNSimple
  • CONSTELLIX
  • DYN DNS
  • Easy DNS
  • NS1
  • Gandi.net
  • Namecheap
  • GoDaddy

As for a sub-domain the record configuration will be detailed in the Koyeb control panel or CLI and looks like below:

NameTypeValue
@ALIASyour-org-uuid.cname.koyeb.app

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

The validation of your domain generally takes under 5 minutes. Note that it could take up to 4 hours, especially if it was incorrectly set up at first.

CAA Records

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.

NameTypeValue
example.tld.CAA0 issue "comodoca.com"
example.tld.CAA0 issue "digicert.com"
example.tld.CAA0 issue "letsencrypt.org"
example.tld.CAA0 issue "pki.goog"
example.tld.CAA0 issuewild "comodoca.com"
example.tld.CAA0 issuewild "digicert.com"
example.tld.CAA0 issuewild "letsencrypt.org"
example.tld.CAA0 issuewild "pki.goog"

Verify your configuration

Ensure your DNS configuration is correct using the dig command.

For a sub-domain

In the case of a sub-domain, 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 is generally that your DNS configuration is not valid or propagated yet.

For an apex domain

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

❯ dig example.tld A

; <<>> DiG 9.10.6 <<>> example.tld A +noall +answer
;; global options: +cmd
example.tld.		300	IN	A	172.67.24.44
example.tld.		300	IN	A	104.22.79.190
example.tld.		300	IN	A	104.22.78.190

If nothing appears, this typically indicates that your DNS configuration is not valid or has not yet propagated.

← Koyeb CLITroubleshooting Deployments →