Skip to content

How do I set up a custom domain?

Every gateway gets a default platform201 address like gigantic-peach-ptarmigan.eu1.platform201.live. You can put a hostname you own in front of it, such as app.mycompany.com or the apex (root) domain mycompany.com, so users reach your deployment on your own domain.

platform201 handles SSL for custom domains. You don't need to set up a certificate.

Before you start

  • A deployment with a gateway node
  • Access to the DNS settings for your domain (Cloudflare, Route 53, Namecheap, GoDaddy, etc.)

1. Open the gateway's custom domain settings

On your graph, find the gateway node. Its Domain row shows the default platform201 address. Click the link icon in the top-right corner of the node.

Gateway node with the custom domain link icon highlighted

2. Enter your hostname

In the Add custom domain dialog, type the hostname you want to use, for example test.platform201.com.

  • Use a hostname on a domain you control.
  • Enter only the hostname: no https:// and no trailing path.

Add custom domain dialog with a hostname entered

Submit the dialog to register the hostname. platform201 then shows the DNS records you need to publish.

3. Add the DNS records at your DNS provider

The domain now appears with a Pending DNS status, along with two CNAME records. Use the copy buttons to copy each value exactly.

Pending DNS status with the two CNAME records to publish

Add both records at your DNS provider:

Type Name Value Purpose
CNAME test.platform201.com gigantic-peach-ptarmigan.eu1.platform201.live Routes traffic for your hostname to the gateway
CNAME _acme-challenge.test.platform201.com <token>.dcv.platform201.live Lets platform201 verify the domain and issue its SSL certificate

The values above are examples. Always copy the records shown for your own domain, because the _acme-challenge value is unique to each one.

Record names at your DNS provider

First, check which domain's DNS settings you are editing. For example, if you are editing mycompany.com, your provider may automatically add .mycompany.com after anything you type in the Name (sometimes called Host) field.

In that case, enter only the part before .mycompany.com:

Hostname you want to create Enter in Name / Host Full DNS name after your provider adds the domain
app.mycompany.com app app.mycompany.com
_acme-challenge.app.mycompany.com _acme-challenge.app _acme-challenge.app.mycompany.com
test.platform201.com (when editing platform201.com) test test.platform201.com
_acme-challenge.test.platform201.com (when editing platform201.com) _acme-challenge.test _acme-challenge.test.platform201.com
mycompany.com (apex / root) @ or leave blank, as your provider instructs mycompany.com
_acme-challenge.mycompany.com _acme-challenge _acme-challenge.mycompany.com

Example DNS editor: the grey suffix is supplied by the provider; only the text inside the Name field is typed. This mockup shows the subdomain app.mycompany.com.

Mock DNS editor for mycompany.com: enter app and _acme-challenge.app in the Name fields; the provider adds .mycompany.com to each.

Avoid repeating the domain. If the provider adds .mycompany.com and you type app.mycompany.com, it may create app.mycompany.com.mycompany.com instead of app.mycompany.com.

Some providers expect the full hostname instead. Check their field hint or preview of the final DNS name before saving. This shortening applies only to the Name / Host field: copy the Value / Target from platform201 in full.

Using Cloudflare?

Set both records to DNS only (grey cloud), not proxied. With the proxy on, platform201 can't verify the domain or issue the certificate.

4. Wait for the domain to become active

DNS changes can take anywhere from a few minutes to a few hours to propagate. Once platform201 detects both records and issues the certificate, the status changes from Pending DNS to Active.

Custom domain showing the Active status

Your deployment is now reachable at https://<your-hostname>. Click the external link icon next to the hostname to open it.

Troubleshooting

The domain stays on Pending DNS. Check that both records exist and match the values shown in platform201 exactly. You can look up what DNS currently returns with:

Open Terminal and run:

dig +short CNAME test.platform201.com
dig +short CNAME _acme-challenge.test.platform201.com

Open a terminal and run:

dig +short CNAME test.platform201.com
dig +short CNAME _acme-challenge.test.platform201.com

If dig isn't installed, install dnsutils on Debian/Ubuntu or bind-utils on Fedora/RHEL using your package manager.

Open PowerShell or Command Prompt and run:

nslookup -type=CNAME test.platform201.com
nslookup -type=CNAME _acme-challenge.test.platform201.com

Replace the example hostnames with your own. The first result should match your gateway's target and the second should match the certificate verification target shown in platform201.

For an apex domain or a flattened DNS record, the traffic record may return IP addresses instead of a CNAME. On macOS or Linux, check with dig +short A mycompany.com and dig +short AAAA mycompany.com; on Windows, use nslookup -type=A mycompany.com and nslookup -type=AAAA mycompany.com. Check the certificate record separately using _acme-challenge.mycompany.com.

If the expected record returns no answer, it may not have propagated yet or may have been created under the wrong name (see the tip in step 3). On macOS or Linux, rerun dig without +short to see the DNS status: NXDOMAIN means the queried name doesn't exist, while SERVFAIL indicates a DNS resolution problem. To compare with a public resolver, add @1.1.1.1 to a dig command or 1.1.1.1 to the end of an nslookup command. Different answers can indicate cached DNS results.

I already have an A record or another record for this hostname. A hostname can't have a CNAME alongside other records. Remove the existing record for that hostname before adding the CNAME.

Can I use a root domain like mycompany.com? Yes. platform201 supports apex (root) domains, so you can use mycompany.com directly. Enter it in the custom domain dialog and publish the DNS records shown for it. At DNS providers that use relative record names, the root domain is usually entered as @ (or left blank), and the certificate verification record as _acme-challenge.