Skip to main content

Custom host names

By default every deplo.io application is just exposed on a generated hostname 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, there are 2 additional things which need to be done:

  • verify ownership of the custom host name's domain
  • your custom host name needs to point to the deplo.io infrastructure

For this, nctl will output 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 will either just need the value of the DNS TARGET column or both values to fullfil the requirements.

Creating CNAME entries for custom hosts​

The easiest and recommended way to verify your custom host name and point it to the deplo.io 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 got propagated (this might take some time), it will verify domain ownership and also point your custom host name to the deplo.io infrastructure in one go.

Please be aware that this will only work if your custom host name is not a domain name itself (a so called 'apex entry'). So for example, if your domain is example.org and you also want to use the host name example.org for your deplo.io application, you will need to execute the steps documented in the apex domain DNS entries section. If your custom host name is www.example.org though, creating the CNAME entry is enough.

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 deplo.io infrastructure then needs to be done by creating 2 different DNS entries, as follows.

Verification via TXT record​

When using apex DNS host names, you will need to 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, you will need to create a TXT record at your DNS provider with the following content:

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

Deplo.io will try to verify this record periodically (which might take some time). Once it is verified the application will start to listen for requests with the given custom hostname.

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 deplo.io infrastructure​

There are several ways to point your custom host name to deplo.io. They will be explained in the following sections.

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

Please 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, you will need to create regular DNS A records for your custom host names. To achieve this, you will need to resolve the DNS TARGET given by nctl to an actual IP address. On Linux or Mac OS 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 you will need to create a DNS A record with the following content at your provider:

example.org   A   178.209.59.205

After the created DNS entry fully propagated you will be able to access your application at https://<your-custom-hostname>. Please be aware that propagation might take some time to finish.