Custom Domains

Learn how to set up custom domains for your brdz applications.

Overview

Custom domains allow you to serve your application from your own domain name instead of the default platform URL.

Prerequisites

• A deployed application
• A domain name you own
• Access to your domain’s DNS settings

Step 1: Add Hostname to Your App

First, ensure you have the correct app context:

# Verify context
brdz ctx:get

# Change context if needed
brdz ctx:use

Add your custom hostname:

brdz hostnames:create example.com

You can add multiple hostnames:

brdz hostnames:create example.com
brdz hostnames:create www.example.com

Step 2: Configure DNS

You need to point your domain to the brdz platform. The exact target will be provided when you add the hostname.

For Subdomains (Recommended)

Use a CNAME record for subdomains like www.example.com:

Type:  CNAME
Name:  www
Value: your-app.brdz-platform.com
TTL:   300 (or automatic)

For Root Domains

Use an A record for root domains like example.com:

Type:  A
Name:  @
Value: 192.0.2.1
TTL:   300 (or automatic)

Using brdz DNS Management

If you’ve delegated your domain to brdz DNS, create records directly:

# Get your zone ID
brdz dns:zones:list

# Add CNAME for www
brdz dns:records:create www.example.com CNAME your-app.brdz-platform.com --zone <zone>

# Add A record for root
brdz dns:records:create example.com A 192.0.2.1 --zone <zone>

Step 3: Wait for DNS Propagation

DNS changes can take time to propagate:

• Typically: 5-30 minutes
• Maximum: Up to 48 hours

Check propagation:

# Check DNS resolution
dig example.com
dig www.example.com

# Or use online tools
# whatsmydns.net
# dnschecker.org

Step 4: SSL Certificate Provisioning

SSL certificates are automatically provisioned:

• Issued via Let’s Encrypt
• Usually completes within 10 minutes
• Automatic renewal before expiration

Check if your site is accessible via HTTPS:

curl -I https://example.com

Common Configurations

Root and WWW

Most sites should configure both:

brdz hostnames:create example.com
brdz hostnames:create www.example.com

DNS configuration:

example.com.        A      192.0.2.1
www.example.com.    CNAME  example.com

Subdomain for API

# Main app
brdz ctx:use  # Select web-app
brdz hostnames:create www.example.com

# API app
brdz ctx:use  # Select api-app
brdz hostnames:create api.example.com

Multiple Environments

# Production
brdz ctx:use  # Select production/web-app
brdz hostnames:create example.com

# Staging
brdz ctx:use  # Select staging/web-app
brdz hostnames:create staging.example.com

# Development
brdz ctx:use  # Select development/web-app
brdz hostnames:create dev.example.com

Verification

Check DNS

# Verify DNS points to correct target
dig example.com
dig www.example.com

# Check specific nameserver
dig @8.8.8.8 example.com

Check SSL

# Test HTTPS connection
curl -I https://example.com

# Check certificate details
openssl s_client -connect example.com:443 -servername example.com

Test in Browser

1. Open your domain in a browser
2. Verify HTTPS is working (lock icon)
3. Check certificate is valid
4. Confirm your application loads

Troubleshooting

DNS Not Resolving

Problem: dig example.com doesn’t return expected IP

Solutions:

1. Verify DNS records are correct at your registrar
2. Wait for propagation (up to 48 hours)
3. Clear local DNS cache:

   # macOS
   sudo dscacheutil -flushcache
   
   # Linux
   sudo systemd-resolve --flush-caches
   
   # Windows
   ipconfig /flushdns

SSL Certificate Issues

Problem: Certificate not issued or invalid

Solutions:

1. Verify DNS is pointing correctly
2. Wait up to 10 minutes for issuance
3. Check no CAA records block Let’s Encrypt
4. Ensure port 80 and 443 are accessible

”Hostname Already Exists”

Problem: Cannot add hostname

Solutions:

1. Check if hostname is added to another app
2. Remove from other app first:

   brdz hostnames:list
   brdz hostnames:delete <hostname-id>

3. Verify you own the domain

WWW Redirect Not Working

Problem: www and non-www don’t redirect properly

Solutions:

1. Add both hostnames:

   brdz hostnames:create example.com
   brdz hostnames:create www.example.com

2. Both will serve the same application
3. Implement redirects in your application if needed

Best Practices

1. Add Both Root and WWW

brdz hostnames:create example.com
brdz hostnames:create www.example.com

2. Use Low TTL During Setup

Set DNS TTL to 300 seconds (5 minutes) while configuring, increase to 3600 (1 hour) once stable.

3. Test Before Migrating

Test with a subdomain first:

brdz hostnames:create test.example.com

4. Document Your Configuration

Keep notes about:

• Which hostnames point to which apps
• DNS provider and login details
• When changes were made

5. Monitor After Changes

After adding hostnames:

• Check application logs
• Monitor traffic and errors
• Test from multiple locations

Advanced: Domain Migration

Migrating an existing domain to brdz:

1. Prepare

# Deploy your app
brdz releases:create release.zip

# Add hostname but DON'T change DNS yet
brdz hostnames:create example.com

2. Test with Hosts File

Test without changing DNS:

# Add to /etc/hosts (macOS/Linux)
192.0.2.1 example.com

# Test in browser
curl https://example.com

Remove the hosts entry when done testing.

3. Lower TTL

At your current DNS provider, lower TTL to 300 seconds and wait for old TTL to expire.

4. Switch DNS

Update DNS records to point to brdz platform.

5. Monitor

Watch for:

• DNS propagation
• SSL certificate issuance
• Application availability
• Error logs

6. Verify

# Check from multiple locations
# Use online DNS checkers
# Test with different devices

See Also

• Hostnames
• DNS Zones
• DNS Records
• DNS Management Guide