Custom Domains¶

Services that are accessed over HTTP(S) are reached through a hostname. How the hostname is determined depends on the service:

Either way, you keep ownership of the DNS for a custom domain, and the same DNS and TLS rules described below apply. Custom domains apply to HTTP(S) services only. TCP services such as PostgreSQL, MariaDB, and Redis are reached on a hostname and port instead. See Network Access for those.

How it works¶

You create a CNAME record that points your domain at a target provided by Servala. When the instance is created, a TLS certificate for your domain is requested automatically so the service is served over HTTPS.

The certificate authority issues the certificate only after it can reach your domain over the public internet to confirm that you control it. This works only once the CNAME record points at the target and the change has propagated through DNS. Set up and verify the record before you create the instance.

You configure the domain while provisioning the instance, in the same step where you set the service parameters (see Provision a Service). Which path you follow depends on whether the service has a managed subdomain.

In both cases, only a subdomain (such as myapp.example.com) is supported. Apex domains (such as example.com) cannot be used as a custom domain.

Optional custom domain via the Advanced dialog¶

Use this path for services with a managed subdomain, such as Codey. Here the custom domain is optional: if you skip it, the instance stays on the managed subdomain.

1. Open the advanced option¶

Below the FQDN field, click Advanced. This opens the "Use a custom domain" dialog.

2. Note the CNAME target¶

The dialog shows a CNAME target, for example cname.app.codey.ch. This is the value your custom domain's CNAME record must point to.

3. Create the CNAME record¶

At your DNS provider, create a CNAME record for the subdomain you want to use, pointing at the target from the dialog. For example:

myapp.example.com.   CNAME   cname.app.codey.ch.

4. Wait for the record to resolve¶

DNS changes take time to propagate. Confirm that your domain already resolves to the target before continuing, for example with dig or nslookup:

dig +short CNAME myapp.example.com

5. Enter the custom subdomain¶

In the Custom subdomain field of the dialog, enter your domain (for example myapp.example.com) and click Apply.

6. Create the instance¶

Finish provisioning and create the instance. The TLS certificate for your custom domain is requested automatically once the instance is created.

Required custom domain in the FQDN field¶

Use this path for services without a managed subdomain, such as Nextcloud and Keycloak. These forms have no Advanced option: the domain is required, and you enter it directly in the FQDN field. The form shows the CNAME target once you enter a domain, so you set up DNS yourself before you create the instance.

1. Enter your domain in the FQDN field¶

In the FQDN field, enter your domain (for example myapp.example.com).

2. Note the CNAME target shown below the field¶

Once a domain is entered, a message appears below the field:

When using a custom domain, you are responsible for DNS configuration. Point a CNAME record to <domain>.

The exact target depends on the cloud provider zone of the service offering, so use the value shown in your own form rather than the example above.

3. Create the CNAME record¶

At your DNS provider, create a CNAME record for your subdomain, pointing at the target from the message. For example:

myapp.example.com.   CNAME   cname.<domain>.

4. Wait for the record to resolve¶

DNS changes take time to propagate. Confirm that your domain already resolves to the target before continuing, for example with dig or nslookup:

dig +short CNAME myapp.example.com

5. Create the instance¶

With the domain in the FQDN field and DNS in place, finish provisioning and create the instance. The TLS certificate for your custom domain is requested automatically once the instance is created.

If the certificate fails to issue¶

If the CNAME record is missing or has not propagated when the instance is created, the certificate cannot be issued and the service has no valid HTTPS certificate. To recover, correct the DNS record so that your domain resolves to the target, then let certificate issuing retry. Once the domain resolves and the authority can confirm control, the certificate is issued and the service is served over HTTPS.

Viewing the custom domain later¶

When a custom domain is in use, the instance detail page shows the CNAME target for the instance, so you can verify or recreate the DNS record at any time.