# 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:

1. **CNAME check:** The platform first looks for a CNAME record on your domain pointing to the proxy domain.
2. **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.
3. **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](https://www.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.