> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suga.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Domains

> Use your own domain names with Suga services

Custom domains let you serve your Suga services from your own domain (e.g., `app.example.com`) instead of the auto-generated Suga domains.

## How It Works

When you add a custom domain to a service, Suga provides the DNS records you need to configure with your DNS provider. Once the records are in place, Suga automatically verifies ownership and provisions TLS certificates. No manual certificate management required.

**What you get:**

* Automatic TLS certificates
* Cloudflare CDN, WAF, and DDoS protection
* Zero-downtime certificate renewals

## Adding a Custom Domain

<Steps>
  <Step title="Select your service">
    Click on the service you want to assign a custom domain to.
  </Step>

  <Step title="Open the Config tab">
    In the properties panel, open the **Config** tab.
  </Step>

  <Step title="Add a custom domain">
    In the **Public Networking** section, click **+ Custom Domain**. Enter your domain name (e.g., `app.example.com`) and the target port your application listens on (e.g., `3000`).
  </Step>

  <Step title="Configure DNS">
    Suga will display the DNS records you need to add. Create a **CNAME** record with your DNS provider pointing your domain to the provided Suga target.

    Example:

    | Type  | Name  | Target                     |
    | ----- | ----- | -------------------------- |
    | CNAME | `app` | `provided-target.suga.app` |
  </Step>

  <Step title="Deploy">
    Click **Deploy Changes**.
  </Step>

  <Step title="Wait for verification">
    Once your DNS records propagate, Suga automatically verifies your domain and provisions a TLS certificate. This typically takes a few minutes.

    <Note>
      DNS verification must complete within **48 hours** of adding the domain. If your DNS records aren't detected in that time, the claim will expire and you'll need to re-add the domain to start a new verification.
    </Note>

    Your service will then be accessible at your custom domain.
  </Step>
</Steps>

## Apex Domains

Apex (root) domains like `example.com` (without a subdomain prefix) require special DNS support because the DNS specification doesn't allow CNAME records at the zone apex.

<Warning>
  Your DNS provider must support **CNAME flattening**, **ANAME**, or **ALIAS** records to use an apex domain. Not all providers support this.
</Warning>

### Supported DNS Providers

Providers that support CNAME flattening or equivalent include:

| Provider                       | Mechanism                             |
| ------------------------------ | ------------------------------------- |
| **Cloudflare**                 | CNAME flattening (automatic for apex) |
| **NS1**                        | ANAME records                         |
| **DNSimple**                   | ALIAS records                         |
| **Constellix / DNS Made Easy** | ANAME records                         |
| **EasyDNS**                    | ALIAS records                         |
| **DigitalOcean DNS**           | ALIAS records (CNAME flattening)      |
| **Namecheap**                  | ALIAS records                         |
| **Netlify DNS**                | ALIAS records                         |

<Note>
  **AWS Route 53** and **Azure DNS** support ALIAS records, but only for pointing to their own services. They do not support arbitrary external targets. These will **not** work for Suga custom domains.
</Note>

Some traditional registrar DNS providers (e.g., GoDaddy) do not support any of these mechanisms. You'll need to either switch to a supported provider or use a subdomain instead.

Check your DNS provider's documentation if you're unsure whether they support this.

### Configuring an Apex Domain

When you add an apex domain, Suga will provide two DNS records:

| Type  | Name | Target / Value             |
| ----- | ---- | -------------------------- |
| CNAME | `@`  | `provided-target.suga.app` |
| TXT   | `@`  | `suga-verification=...`    |

1. Add both the **CNAME** (or ALIAS/ANAME equivalent) and the **TXT** record with your DNS provider
2. Wait for DNS propagation and automatic verification
3. Deploy your changes

<Note>
  If your DNS provider doesn't support CNAME flattening, you can use a subdomain like `www.example.com` or `app.example.com` and redirect to it from the apex domain.
</Note>

## Domains Already Using Cloudflare

If your domain is already on Cloudflare, you'll need to adjust the proxy setting for the CNAME record that points to Suga.

<Warning>
  Cloudflare's proxy (orange cloud) must be **disabled** for the CNAME record pointing to Suga. Set the record to **DNS only** (grey cloud). Suga cannot verify your domain while the Cloudflare proxy is enabled, because it hides the underlying CNAME target.
</Warning>

Suga provides its own Cloudflare CDN, WAF, and DDoS protection for custom domains, so disabling the proxy on your side does not reduce protection, your traffic is still routed through Cloudflare's edge network via Suga.

## Domain Conflicts

A domain can only be active on one Suga environment at a time. If another organization has already verified and activated the same domain, you'll receive an error when trying to add it.

Unverified (pending) claims from other organizations do not block you, only proven ownership counts. If you need to move a domain between environments within your organization, remove it from the original environment first, then add it to the new one.

## Common Questions

<AccordionGroup>
  <Accordion title="How long does DNS verification take?">
    Usually a few minutes, but DNS propagation can take up to 48 hours depending on your provider and TTL settings. If verification doesn't complete within 48 hours, the claim expires and you'll need to re-add the domain.
  </Accordion>

  <Accordion title="Can I add multiple custom domains to one service?">
    Yes. Add each domain separately through the Public Networking configuration.
  </Accordion>

  <Accordion title="Do I need to manage SSL/TLS certificates?">
    No. Suga automatically provisions and renews SSL/TLS certificates for all custom domains.
  </Accordion>

  <Accordion title="Can I use both a custom domain and the auto-generated domain?">
    Yes. The auto-generated Suga domain continues to work alongside your custom domain.
  </Accordion>

  <Accordion title="Why can't I use an apex domain with my DNS provider?">
    Standard DNS does not allow CNAME records at the zone apex. Your provider needs to support CNAME flattening, ANAME, or ALIAS records. If it doesn't, use a subdomain like `www.example.com` with a redirect instead.
  </Accordion>

  <Accordion title="My domain is on Cloudflare and verification is stuck">
    Make sure the CNAME record pointing to Suga has the Cloudflare proxy **disabled** (grey cloud / DNS only). Suga can't verify the CNAME target while it's hidden behind Cloudflare's proxy.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Networking" icon="network-wired" href="/concepts/networking">
    Learn about HTTPS endpoints, TCP proxy, and private networking
  </Card>

  <Card title="CDN and Regions" icon="globe" href="/reference/cdn-and-regions">
    How Cloudflare's edge and Suga regions route traffic
  </Card>

  <Card title="Service Configuration" icon="gear" href="/reference/configuration">
    Configure environment variables, resources, and scaling
  </Card>
</CardGroup>