Title: Custom Domains

---

Custom Domains

Custom domains allow you to serve your application on a domain you own instead of the default platform-provided URL.

Overview

After configuring a custom domain, the platform verifies that your DNS is correctly set up before activating the domain. This ensures traffic is properly routed through the application proxy.

DNS Configuration

To connect your custom domain, you must point it to the platform's proxy domain using a DNS record. The platform supports two record types depending on your domain setup:

CNAME Records (Recommended for Subdomains)

A CNAME record is the standard way to point a subdomain to the proxy domain.

When to use: Use a CNAME record when your custom domain is a subdomain (e.g., app.example.com, www.example.com).

Example:

| Type  | Name              | Value                          |
|-------|-------------------|-------------------------------|
| CNAME | app.example.com   | your-proxy-domain.platform.io |

Note: CNAME records cannot be used on apex/root domains (e.g., example.com) because the DNS specification does not allow it. Use an ALIAS or ANAME record instead.

ALIAS / ANAME Records (Required for Apex/Root Domains)

Some DNS providers offer proprietary record types called ALIAS or ANAME that behave like CNAME records but are allowed on apex/root domains.

When to use: Use an ALIAS or ANAME record when your custom domain is an apex/root domain (e.g., example.com) and your DNS provider supports it.

Example:

| Type  | Name        | Value                          |
|-------|-------------|-------------------------------|
| ALIAS | example.com | your-proxy-domain.platform.io |

ALIAS and ANAME records are resolved by your DNS provider into A records (IP addresses). The platform automatically detects this by comparing the resolved IP addresses of your domain against the proxy domain — no additional configuration is required on your part.

DNS providers that support ALIAS/ANAME records include:
Cloudflare (CNAME flattening at the apex)
DNSimple (ALIAS record)
DNS Made Easy (ANAME record)
Route 53 (ALIAS record)

Note: If your DNS provider does not support ALIAS or ANAME records, you will need to use a subdomain with a CNAME record or manually configure A records pointing to the proxy's IP addresses. Contact support if you need assistance.

Verification Process

Once you have added the DNS record, the platform performs an automated DNS check to confirm the configuration is correct.

The verification logic works as follows:
CNAME check: The platform first looks for a CNAME record on your domain pointing to the proxy domain.
ALIAS/ANAME fallback: If no CNAME record is found, the platform resolves the A records (IPv4 addresses) for both your domain and the proxy domain. If they share at least one IP address, the domain is considered correctly configured via an ALIAS/ANAME record.
Failure: If neither condition is met, the verification fails and guidance is provided on what to fix.

Verification Statuses

| Status    | Meaning                                                                 |
|-----------|-------------------------------------------------------------------------|
| ok      | DNS is correctly configured. The domain is active or ready to activate. |
| missing | No valid DNS record was found. Follow the instructions provided.        |
| error   | An unexpected DNS lookup error occurred. Try again or contact support.  |

Troubleshooting

My domain verification fails even though I added the DNS record.

DNS changes can take time to propagate. Wait up to 48 hours and try verifying again. You can check propagation status using tools like whatsmydns.net.

I'm on an apex domain and my DNS provider doesn't support ALIAS/ANAME.

Consider using a www subdomain with a CNAME record (e.g., www.example.com) and setting up a redirect from your apex domain to www. Many DNS providers support HTTP redirects or URL forwarding at the apex level.

The verification shows my domain resolves to different IP addresses than the proxy.

Ensure your ALIAS or ANAME record is pointing to the correct proxy domain value. If you recently changed the record, allow time for DNS propagation before retrying.