# Custom Domains

This guide walks you through adding and configuring custom domains for your Sherpa.sh projects. You can choose between automated DNS management or manual record configuration.

## Overview

Sherpa.sh supports unlimited custom domains on any paid plan. You have two configuration options:

* **Automated (Recommended)**: Point your nameservers to Sherpa.sh for automatic DNS management
* **Manual**: Maintain your DNS provider and add specific records per project

## Prerequisites

* Paid plan on Sherpa.sh
* Domain registered with a DNS provider
* Access to your domain's DNS settings

## Adding a Custom Domain

1. Navigate to the **Domains** tab in your Sherpa.sh dashboard
2. Click **Add New Domain**
3. Enter your domain name (e.g., `example.com`)
4. Click **Save**

### Method 1: Automated DNS Management (Recommended)

This method provides the most seamless experience with automatic SSL certificate generation and CDN optimization.

#### **Step 1: Update Nameservers**

After adding your domain, navigate to the DNS Management section:

1. Go to your domain's settings page
2. Note the Sherpa.sh nameservers:
   * `ns1.sherpa.sh`
   * `ns2.sherpa.sh`
3. Update your domain registrar's nameservers to point to Sherpa.sh

{% hint style="warning" %}
**Important**: Some providers (like GoDaddy) don't support CNAME-based nameserver forwarding. For these providers, use the direct Bunny.net nameservers (our underlying DNS provider):

* `kiki.bunny.net`
* `coco.bunny.net`

Alternatively, you can use the IP addresses directly:\


* `91.200.176.1`
* `109.104.147.1`
{% endhint %}

#### **Step 2: Link Domain to Application**

1. Navigate to your domain in the Sherpa.sh dashboard
2. Click **Link Application**
3. Select your target application from the dropdown
4. Click **Save**

### Method 2: Manual DNS Configuration

Use this method if you prefer to manage DNS through your existing provider.

#### **Step 1: Link Domain to Application**

Follow the same steps as automated method to link your domain to an application.

#### **Step 2: Add Required DNS Records**

Navigate to your application's page's domain settings to view [required records](#required-dns-records) and add them in your DNS provider

### Manual DNS Configuration: Required Records

When managing DNS through your existing provider, you'll need to configure specific records to route traffic to Sherpa.sh infrastructure. Here's exactly what each record does and important considerations for root domain routing.

#### Understanding the Record Structure

Each DNS record serves a specific purpose in the routing chain:

* **Application routing**: Directs user traffic to your application
* **SSL validation**: Proves domain ownership for certificate generation
* **Static assets**: Optimizes delivery of images, CSS, and JavaScript files

#### Required DNS Records by Domain Type

#### **Subdomain Configuration (Recommended)**

For subdomains like `www.example.com` or `app.example.com`:

```
Type: CNAME
Name: www (or your chosen subdomain)
Value: example.sherpa.softwareTTL: 3600
```

**What this does**: Routes all traffic for your subdomain through Sherpa.sh's CDN network, providing optimal performance and automatic scaling.

**Static assets optimization**:

```
Type: CNAME
Name: static-www (or static-[yoursubdomain])
Value: static-example.sherpa.softwareTTL: 3600
```

{% hint style="success" %}
This is a legacy record left over from previous architectures, it will soon be removed from the dashboard.  It is required for now, but will be removed in the future.  When we remove it, you will not have to do anything on your side, everything will continue working as expected.
{% endhint %}

#### **Root Domain Configuration**

If you want to use your root domain as your main url, root domains (like `example.com`) have DNS limitations that require special handling:

<figure><img src="https://1086021854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F4RCQ8zlKmeSmdasWK4qa%2Fuploads%2FGztvFqroVOenCNqC75ji%2FScreenshot%202025-07-09%20at%2013.54.51.png?alt=media&#x26;token=3956748f-bf9f-455b-a49f-39f03fc49c3d" alt="" width="375"><figcaption><p>Root domain configuration is required when this switch is enabled</p></figcaption></figure>

**Option 1 - ALIAS/ANAME Record** (Best Performance):

```
Type: ALIAS (or ANAME/FLATTENING depending on provider)
Name: @ (or leave blank)
Value: sherpa.sherpa.softwareTTL: 3600
```

**Supported providers**: Cloudflare, AWS Route53, DNSimple, Namecheap, and more\
**Benefits**: Full CDN support, optimal performance, proper SSL handling

{% hint style="info" %}
#### Why CNAMEs Don't Work on Root Domains

CNAME records cannot be placed at the root domain level because DNS standards dictate that the root domain must not have CNAME records due to the way DNS queries are resolved. A CNAME at the root would conflict with other essential DNS records like MX records.

#### How Some Providers Support Root Domain CNAMEs

Some DNS providers use proprietary solutions like ALIAS, ANAME, or CNAME flattening to overcome this limitation. These custom records allow the root domain to redirect traffic similarly to a CNAME while maintaining compatibility with the DNS protocol. This ensures seamless integration with services that require domain aliases without breaking DNS rules.  But not all providers support this functionality.
{% endhint %}

**Option 2 - A Record** (Compatibility Fallback):

{% hint style="danger" %}
It is **strongly** recommend that you avoid using the Option 2.  If your provider does not support Option 1 it is better to use a subdomain `www.example.com` instead of `example.com` as the main url of your website.
{% endhint %}

```
Type: A
Name: @ (or leave blank)
Value: [Load balancer IP]
TTL: 3600
```

**When to use**: Only when your DNS provider doesn't support ALIAS/ANAME records \
**Limitations**:

* Bypasses CDN, resulting in slower global performance
* Direct server connection increases bandwidth usage
* No automatic failover if IP changes
* May impact your billing due to increased origin bandwidth consumption

#### **Performance Impact Comparison**

**Subdomain with CNAME** (Optimal):

* Request path: User → CDN Edge → Origin Server
* Benefits: Caching, compression, DDoS protection
* Latency: 20-50ms globally

**Root domain with A record** (Suboptimal):

* Request path: User → Origin Server (direct)
* Limitations: No caching, higher latency, increased bandwidth
* Latency: 100-300ms depending on user location

#### SSL Certificate Validation Record

Required for all configurations to enable HTTPS:

```
Type: CNAME
Name: _acme-challenge
Value: _acme-challenge.example.com.validation.sherpa.software
TTL: 300
```

**Important**: This record is used by Let's Encrypt to verify domain ownership. Keep it even after SSL activation for automatic renewals.

## Domain Configuration Options

Once linked, configure these settings on your domain's page:

#### Root Domain Routing

* **Route root domain to this project**: Directs `example.com` to your application. Requires [root domain configuration](#root-domain-configuration).
* **Redirect root domain to subdomain**: Redirects `example.com` → `www.example.com`

#### Best Practices

1. **Use Subdomains**: We recommend using `www` or another subdomain as your primary domain rather than the root domain for better CDN compatibility
2. **Root Domain Limitations**:
   * Some DNS providers don't support CNAME records on root domains
   * Using A records bypasses CDN benefits, potentially increasing origin bandwidth usage
3. **SSL Certificates**: Keep the `_acme-challenge` record even after SSL generation for future renewals

### Verification and Troubleshooting

#### Check DNS Propagation

After updating records:

1. Click **Refresh** in the domain settings
2. Check status indicators (✓ = configured correctly)
3. Allow 5-48 hours for full DNS propagation

#### Common Issues

**Nameserver Conflicts:**

* Ensure no conflicting records exist at your DNS provider
* Remove any existing A/CNAME records for configured subdomains

**SSL Certificate Errors:**

* Verify `_acme-challenge` record is correctly configured
* Check for typos in the validation record value

**CDN Bypass Warning:**

* If using A records for root domain, traffic bypasses CDN
* Consider upgrading your plan if hitting bandwidth limits

### Support

Need assistance? Join our Discord community: [discord.sherpa.sh](https://discord.sherpa.sh)

####
