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

# Custom Domains

> Connect your own domain name to your RepoCloud applications

## Using Custom Domains

By default, every application deployed on RepoCloud receives a randomly assigned subdomain on one of our hosting domains, in the format `https://<your-app-id>.<hosting-domain>` (we use several different domains for auto-generated URLs). However, you can connect your own domain name to provide a professional, branded experience for your users.

<Note>
  Custom domains allow you to use your brand's domain name while hosting your application on RepoCloud, giving your application a professional appearance and better brand recognition.
</Note>

## Why Use a Custom Domain?

<CardGroup cols={2}>
  <Card title="Professional Branding" icon="briefcase">
    Present a cohesive brand identity with your own domain
  </Card>

  <Card title="Better SEO" icon="magnifying-glass">
    Establish and maintain search engine optimization
  </Card>

  <Card title="Business Credibility" icon="handshake">
    Enhance trust with a professional domain name
  </Card>

  <Card title="Marketing Consistency" icon="bullhorn">
    Maintain consistent branding across all channels
  </Card>
</CardGroup>

## Setting Up a Custom Domain

Adding a custom domain to your RepoCloud application is a straightforward process:

<Steps>
  <Step title="Access Domain Settings">
    Navigate to your application's management page and click the "Add Custom Domain" button.
  </Step>

  <Step title="Add Your Domain">
    Enter your domain (e.g., `app.yourdomain.com`) in the input field and click "Submit".

    <Note>
      If you enter a root domain (e.g., `yourdomain.com` without a subdomain), RepoCloud will warn you that your DNS provider must support ANAME, ALIAS, or CNAME-flattening records, and will offer to use a `www` subdomain instead. See [Using Apex Domains](#using-apex-domains) below.
    </Note>
  </Step>

  <Step title="Configure DNS Records">
    RepoCloud displays the exact DNS records you need to add at your domain registrar. You'll add two CNAME records:

    * A CNAME for your subdomain pointing to your application's auto-generated address (e.g., `app` → `<your-app-id>.<hosting-domain>.`)
    * A CNAME for `_acme-challenge` pointing to the SSL verification target shown in the dashboard (used to issue your SSL certificate)

    Each record includes a copy button, and the dashboard shows a live status indicator for each record.
  </Step>

  <Step title="Wait for DNS Propagation">
    DNS changes can take up to 24-48 hours to propagate globally, though they often take effect much sooner.
  </Step>

  <Step title="Confirm and Check Status">
    Click the "Confirm and Check Status" button in the dashboard. Once both records verify, RepoCloud automatically issues an SSL certificate and routes your domain to your application.
  </Step>
</Steps>

<Tip>
  To remove a custom domain later, return to your application's management page and click "Remove Domain".
</Tip>

## DNS Record Types Explained

When setting up a custom domain, you may need to configure different DNS record types:

<AccordionGroup>
  <Accordion title="CNAME Record (Routing)">
    A CNAME (Canonical Name) record maps an alias domain to a true or canonical domain. For RepoCloud, this maps your domain to your application's auto-generated address.

    Example: `app.yourdomain.com` → `<your-app-id>.<hosting-domain>.`
  </Accordion>

  <Accordion title="CNAME Record (SSL Verification)">
    RepoCloud also asks you to add a CNAME record on the `_acme-challenge` name of your domain, pointing to the verification target shown in your dashboard. This record allows SSL certificates to be issued and renewed automatically for your domain.

    Example: `_acme-challenge.yourdomain.com` → `yourdomain.com.<unique-id>.dcv.cloudflare.com.`
  </Accordion>

  <Accordion title="ALIAS / ANAME Records (Apex Domains)">
    Apex (root) domains normally cannot use CNAME records. Some DNS providers offer ALIAS or ANAME records, or CNAME flattening, which provide CNAME-like behavior at the apex. These are required if you want to point a root domain (e.g., `yourdomain.com`) at RepoCloud.
  </Accordion>
</AccordionGroup>

## Using Apex Domains

An apex domain (also called a root domain or naked domain) is a domain without a subdomain prefix, like `example.com` instead of `www.example.com`.

To use an apex domain with RepoCloud, your DNS provider must support CNAME-like functionality for apex domains through features like:

* ALIAS records
* ANAME records
* CNAME flattening

Some DNS providers, such as GoDaddy, do not support these features. If yours doesn't, you can:

* Use a subdomain (like `www.yourdomain.com`) instead — RepoCloud offers this option automatically when you enter a root domain
* Point your nameservers to Cloudflare first, or switch to another DNS provider that supports ALIAS/ANAME records (such as Route 53 or DNSimple)

<Tip>
  Using `www.yourdomain.com` instead of just `yourdomain.com` often provides better flexibility and performance.
</Tip>

## SSL Certificates

RepoCloud automatically provisions and manages SSL certificates for your custom domains:

* **Automatic Provisioning**: SSL certificates are automatically issued once your DNS records are verified
* **Automatic Renewal**: Certificates are renewed automatically before they expire
* **HTTPS Enforcement**: All traffic to your application is served over HTTPS

<Note>
  SSL certificate issuance typically takes a few minutes after DNS verification is complete.
</Note>

## SSL Certificate Issuance Method

RepoCloud uses DNS-based domain validation for SSL certificate issuance:

### How DNS Validation Works

<Steps>
  <Step title="Record Generation">
    When you add a domain, RepoCloud generates a unique `_acme-challenge` CNAME target for it
  </Step>

  <Step title="Record Creation">
    You add the `_acme-challenge` CNAME record (shown in your dashboard) at your DNS provider, alongside the routing CNAME
  </Step>

  <Step title="Domain Validation">
    The certificate authority validates domain control by resolving the `_acme-challenge` record
  </Step>

  <Step title="Certificate Issuance">
    Once validated, the SSL certificate is issued and applied to your application, and renewals happen automatically as long as the record stays in place
  </Step>
</Steps>

<Warning>
  Do not delete the `_acme-challenge` CNAME record after setup—it is required for automatic certificate renewal.
</Warning>

### Multiple Subdomains on the Same Domain

If you're using multiple subdomains of the same domain (e.g., `app1.yourdomain.com` and `app2.yourdomain.com`) for different RepoCloud applications, there are some important considerations:

<Warning>
  Each subdomain must resolve to the correct application, and each application generates its own verification records. This can create complications when you have multiple applications using subdomains of the same root domain.
</Warning>

### Recommended Solution: Cloudflare

<CardGroup cols={1}>
  <Card title="Use Cloudflare for Multiple Subdomains" icon="cloud">
    We strongly recommend using Cloudflare as your DNS provider when hosting multiple applications on different subdomains of the same domain. Cloudflare's proxy functionality helps resolve the ACME challenge validation issues.
  </Card>
</CardGroup>

#### Benefits of Using Cloudflare:

* **Proxy Mode**: Cloudflare's proxy capabilities help route SSL validation correctly
* **SSL Flexibility**: Better handling of multiple SSL certificates for different subdomains
* **Performance**: Additional CDN and caching benefits
* **Security**: Additional protection against DDoS and other attacks

<Tip>
  To set up Cloudflare for your domain, transfer your nameservers to Cloudflare and enable the proxy setting (orange cloud icon) for each subdomain record.
</Tip>

## Managing Multiple Domains

You can add multiple domains to a single application:

1. Follow the same process for each domain you want to add
2. All domains will point to the same application
3. Each domain will receive its own SSL certificate

This is useful for:

* Supporting multiple brands or regions
* Migrating from an old domain to a new one
* Creating specialized landing pages

## Troubleshooting Custom Domains

<AccordionGroup>
  <Accordion title="DNS Verification Failed">
    * Verify that you've added the correct DNS records at your domain registrar
    * Check for typos in the DNS record values
    * Allow sufficient time for DNS propagation (up to 48 hours)
    * Use a DNS lookup tool like [DNS Checker](https://dnschecker.org) to verify your records are visible
  </Accordion>

  <Accordion title="SSL Certificate Issues">
    * Ensure domain verification is complete
    * Check that your DNS records are correctly configured
    * Wait at least 30 minutes for the SSL certificate to be issued
    * If issues persist for more than 24 hours, contact support
  </Accordion>

  <Accordion title="Domain Shows 'Not Secure'">
    * This typically means the SSL certificate hasn't been issued yet
    * Verify that DNS configuration is correct
    * Wait for SSL certificate issuance to complete
    * Check that you're accessing the site via HTTPS, not HTTP
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Environment Variables" icon="gear" href="/user-guide/environment-variables">
    Configure application-specific settings through environment variables
  </Card>

  <Card title="Scaling" icon="chart-line" href="/user-guide/scaling">
    Learn how to scale your application resources
  </Card>

  <Card title="Updates" icon="arrows-rotate" href="/user-guide/updates">
    Keep your application updated with the latest features and security patches
  </Card>
</CardGroup>