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

Caution

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

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

Tip

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.

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:

Root domain configuration is required when this switch is enabled

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

Danger

It is strongly recommend that you use Option 1. 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.

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

Note

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.

Option 2 - A Record (Compatibility Fallback):

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.

Debugging DNS Routing

If you are having issues setting up your custome domain's DNS routing. Please follow the following steps:

1. Check DNS propagation

If you are using our Automated DNS Management (method 1) your domain won't be available until propagation is completed. To check propagation you can use https://www.whatsmydns.net/#NS/ and search for your domain's NS server propogation. Once your nameservers are fully propogated, redeploy the application that your've linked your custom domain to.

If you are using Manual Managment (method 2) your domain won't be available until propagation is completed. You can use https://www.whatsmydns.net/#CNAME/ to check the CNAME propagation of all the required fields on the domains page of your application.

2. Redeploy application

Once propogation is complete, redepooy your application to have it pick up the new DNS routing changes. If you deploy before propogation is completed your custom domain, SSL cert, or other routing may not work.

3. Open a Support Ticket

If you still have trouble, visit discord.sherpa.sh and open a ticket in the #support channel with your account email, application, and domain information.

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.
• 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