Skip to main content

Custom Host Names

By default, every Deploio application gets a generated host name in the deploio.app domain. If you want to use your own domain, you can do so using the --hosts flag of nctl when creating the application.

--hosts=HOSTS,...    Host names where the application can be accessed. If empty,
                     the application will just be accessible on a generated
                     host name on the deploio.app domain.

$ nctl create app go-example --hosts=custom.host.example.com

With nctl, you can also update your custom host names after the application was created:

$ nctl update app go-example --hosts=custom.host.example.com,other.custom.host.example.com

Configuration​

Once you use custom host names for your application, you need to complete two additional steps:

  • Verify ownership of the custom host name's domain.
  • Point your custom host name to the Deploio infrastructure.

For this, nctl outputs a TXT RECORD and DNS TARGET once the first Build and Release was successfully created. You can also get the TXT record and CNAME content by using nctl after you created the application by using the --dns flag:

$ nctl get app test-app --dns

NAME        TXT RECORD                                          DNS TARGET
go-example  deploio-site-verification=go-example-nine-46e4146   go-example.46e4146.deploio.app

Depending on the kind of host name you want to add, you either need the value of the DNS TARGET column or both values to fulfil the requirements.

Creating CNAME Entries for Custom Hosts​

The easiest and recommended way to verify your custom host name and point it to the Deploio infrastructure in one step, is to create a CNAME record for it which points to the DNS TARGET given by nctl. So, for example, when using the custom host name custom.host.example.org in the above application go-example, you would need to create the following CNAME record at your DNS provider:

custom.host.example.org   CNAME   go-example.46e4146.deploio.app

After the DNS record propagates (this might take some time), it verifies domain ownership and also points your custom host name to the Deploio infrastructure in one go.

If your custom host name is an apex domain (a so-called 'apex entry'), such as example.org itself, you can't use a CNAME — see Apex Domain DNS Entries. For subdomains like www.example.org, creating the CNAME entry is sufficient.

CNAME Chaining

Deploio follows the full CNAME chain during domain verification, so your CNAME record can itself point to another CNAME. All domains in the chain must be under your control or explicitly trusted. If any intermediate domain expires and is re-registered by a third party, they could take over verification of your host name.

To disable CNAME chain following, contact our support.

Apex Domain DNS Entries​

If your custom host name is an actual domain name (for example: example.org) rather than a subdomain, you will not be able to create a CNAME DNS record for it. The CNAME type is not permitted for so-called "apex DNS entries" (entries on the root level of your domain). Domain verification and pointing your host name to the Deploio infrastructure then requires creating two different DNS entries, as follows.

Verification via TXT Record​

When using apex DNS host names, create a DNS TXT record which resolves to the value displayed in the TXT RECORD column of the nctl output. The TXT record is used to verify domain ownership of the domain which hosts your custom host name. For example, to prove that you are permitted to use the custom host name 'example.org' for the above application go-example, create a TXT record at your DNS provider with the following content:

example.org   TXT   deploio-site-verification=go-example-nine-46e4146

Deploio tries to verify this record periodically (which might take some time). Once Deploio verifies the record, the application starts listening for requests with the given custom host name.

You can see all verified and unverified hosts by using nctl:

$ nctl get apps

NAME           HOSTS                                   UNVERIFIED_HOSTS
go-example     go-example.46e4146.test.deploio.app     example.org

Pointing Your Host Name to the Deploio Infrastructure​

There are several ways to point your custom host name to Deploio. The following sections explain each method.

DNS ALIAS Record​

Some DNS providers allow to create so-called ALIAS DNS records. ALIAS records behave like CNAME records, but do appear as a normal DNS A record to the outside world. If your DNS provider supports ALIAS records, we recommend using them. Just create a DNS entry of type ALIAS which points to the value displayed in the DNS TARGET column of nctl. Again using the go-example application from above, the corresponding DNS entry needs to look like:

example.org   ALIAS   go-example.46e4146.deploio.app

Note that it might take some time until the record is fully propagated.

DNS A Record​

If there is no support for ALIAS DNS records at your provider, create regular DNS A records for your custom host names. To achieve this, resolve the DNS TARGET given by nctl to an actual IP address. On Linux or macOS systems this can be done by using the host (or any equivalent) utility:

$ host test-app.edcd8e7.deploio.app

test-app.edcd8e7.deploio.app is an alias for deploio.296dc8b.ingressnginx.nineapis.ch.
deploio.296dc8b.ingressnginx.nineapis.ch has address 178.209.59.205

In that case, create a DNS A record with the following content at your provider:

example.org   A   178.209.59.205

After the DNS entry fully propagates, you can access your application at https://<your-custom-hostname>. Propagation might take some time.