Custom Domain Setup Tutorial

Tutorial ID: custom-domain-setup
Version: 1.0.0
Difficulty: Intermediate
Estimated Duration: 5-6 minutes (plus DNS propagation time)

Overview

This interactive tutorial guides users through the complete process of adding and verifying a custom domain in Jetty, including DNS configuration, SSL/TLS certificate provisioning, and tunnel creation. It addresses the most common pain points in DNS setup and provides detailed troubleshooting guidance at each step.

Learning Objectives

By completing this tutorial, users will:

1. Understand how to add and verify a custom domain in Jetty
2. Configure DNS records correctly (TXT for verification, CNAME/A for routing)
3. Navigate DNS propagation delays and troubleshoot issues
4. Create tunnels using their verified custom domain
5. Verify SSL/TLS certificates are working properly
6. Use traffic inspection tools to debug domain-related issues

Prerequisites

• Plan: Captain tier or higher (custom domains feature)
• Access: User must have access to domain's DNS settings
• Knowledge: Basic understanding of DNS records (helpful but not required)
• Credentials: Domain registrar/DNS provider login credentials

Tutorial Flow

Step 1: Navigate to Custom Domains

Duration: ~15 seconds

Users navigate to the Custom Domains settings page where they can manage all domains.

Validation: Route-based check for settings/domains

Key Teaching Points:

• Location of settings in the dashboard
• Permission requirements for domain management
• Plan requirements visibility

Step 2: Enter Your Domain Name

Duration: ~30 seconds

Users learn best practices for choosing a domain or subdomain for Jetty tunnels.

Critical Guidance:

• Recommended: Use subdomains (api.example.com, dev.example.com)
• Avoid: Root domains (example.com) unless user understands implications
• Format: Domain only, no protocol or paths

Common Mistakes Addressed:

• Including http:// or https:// prefix
• Adding trailing slashes or paths
• Using domains they don't own or control
• Confusing root domain vs subdomain implications

Validation: Input-based check when domain is submitted

Step 3: Copy the Verification TXT Record

Duration: ~30 seconds

Users receive their unique DNS verification record and learn how DNS TXT records work.

Critical Information Provided:

• Name/Host: _jetty-verification.{subdomain}.{domain}
• Type: Always TXT
• Value: Unique token (40-60 characters)

Key Pain Point Addressed: DNS provider format variations

Different DNS providers display record names differently:

• Full format: _jetty-verification.api.example.com (most providers)
• Subdomain only: _jetty-verification.api (Cloudflare, some others)
• Prefix only: _jetty-verification (when adding to root)

User Experience Consideration: Tutorial emphasizes keeping this page open or bookmarking it, as users will need to reference these values while working in their DNS provider's interface.

Step 4: Add TXT Record to DNS Provider

Duration: 2-5 minutes (varies by provider)

This is the most critical step where the majority of issues occur. The tutorial provides detailed, provider-specific guidance.

DNS Provider Coverage

The tutorial includes detailed instructions for:

1. Cloudflare (high popularity)

   • Proxy status warning (gray cloud vs orange cloud)
   • Subdomain format (provider adds domain automatically)
   • TTL recommendations

2. AWS Route 53 (high popularity)

   • Quote wrapping requirement
   • Hosted zone selection
   • Record name format

3. Google Cloud DNS (medium popularity)

   • Trailing dot requirement
   • Zone selection
   • Quote format

4. Namecheap (medium popularity)

   • Host field format
   • @ symbol usage for root
   • TTL options

5. GoDaddy (high popularity)

   • Minimum 1-hour TTL limitation
   • Expected longer propagation times

6. Generic/Other Providers

   • General guidance that works across providers

Common Issues Per Provider

Each provider section includes:

• Step-by-step instructions with exact field names
• Common mistakes specific to that provider
• Impact of each mistake
• Solutions to fix the issue

Example - Cloudflare Issues:

• Orange cloud (Proxied) enabled → TXT records won't be visible → Solution: Turn to gray cloud
• Domain duplication (entering full domain when provider adds it) → Wrong record name → Solution: Use subdomain part only

General Troubleshooting

• DNS provider shows error when saving
• Uncertainty about whether record saved correctly
• Format confusion (quotes, spaces, case sensitivity)

Validation: Manual confirmation that user has added the record

Step 5: Verify DNS Propagation

Duration: 1-30 minutes (varies widely)

This step addresses DNS propagation delays, the second-most common pain point.

Propagation Time Expectations

The tutorial provides realistic timelines per provider:

DNS Checking Tools

The tutorial teaches users four different methods to check DNS propagation:

1. dig (Mac/Linux command line)

   dig TXT _jetty-verification.api.example.com +short
   

   • Expected output format
   • How to interpret results
   • What success/failure looks like

2. nslookup (Universal command line)

   nslookup -type=TXT _jetty-verification.api.example.com
   

   • Cross-platform availability
   • Output interpretation
   • Error messages explained

3. Google DNS Lookup (https://dns.google)

   • Web-based, no installation needed
   • How to use the interface
   • Reading results

4. DNSChecker.org (https://dnschecker.org)

   • Global propagation checking
   • Multiple location visibility
   • Understanding partial propagation (not all locations need to be green)

Propagation Factors Explained

Users learn what affects DNS propagation:

• TTL (Time To Live): Lower = faster updates
• Provider infrastructure: Larger providers = faster propagation
• Geographic location: Some regions update before others
• DNS caching: Local/ISP caches may delay visibility

Troubleshooting Stuck Propagation

Symptom: Waiting over 1 hour with no propagation

Possible Causes:

• Record added incorrectly
• DNS provider has pending changes not activated
• Very high TTL (4+ hours)
• Wrong DNS zone or account

Solutions:

• Verify record exists in DNS provider
• Check for "Activate Changes" buttons
• Look for Cloudflare orange cloud (should be gray)
• Confirm correct zone selected

Validation: Manual confirmation that user can see the TXT record in DNS

Step 6: Complete Domain Verification

Duration: ~30 seconds

Users trigger Jetty's verification process and SSL certificate provisioning.

What Happens Behind the Scenes

1. Jetty queries multiple DNS servers for the TXT record
2. Record value is compared against generated token
3. If match, domain status changes to "Verified"
4. SSL/TLS certificate automatically requested from Let's Encrypt
5. Certificate provisioning completes in 1-2 minutes

Error Handling

The tutorial provides specific guidance for each error type:

Error: "TXT record not found"

• Meaning: DNS servers can't see the record yet
• Solutions: Wait longer, verify with DNS tools, check provider settings

Error: "TXT record value mismatch"

• Meaning: Record exists but value is wrong
• Solutions: Compare character-by-character, check for truncation, look for extra spaces

Error: "Domain already in use"

• Meaning: Domain verified on another Jetty account
• Solutions: Check with teammates, remove from other account, contact support

Error: "Certificate provisioning failed"

• Meaning: Rare SSL certificate issue
• Solutions: Wait 5 minutes, check CAA records, contact support

Validation: Status-based check for domain_verified

Step 7: Add CNAME/A Record

Duration: 2-5 minutes (plus propagation)

Users learn to point their domain to Jetty's edge servers for actual traffic routing.

CNAME vs A Records

CNAME (for subdomains - recommended):

Name:  api.example.com
Type:  CNAME
Value: custom.tunnels.usejetty.online
TTL:   300

Benefits:

• Automatic updates if Jetty changes infrastructure
• More flexible
• Standard practice for subdomains

A Record (for root domains):

Name:  example.com
Type:  A
Value: 203.0.113.10
TTL:   300

Limitations:

• Manual updates needed if IPs change
• Affects all subdomains unless overridden
• Less flexible

Cloudflare-Specific Guidance

Critical instruction: Start with gray cloud (DNS only)

• Test tunnel functionality first
• Enable orange cloud (proxy) only after confirming it works
• Cloudflare proxy can interfere with WebSockets initially

Common Mistakes

1. Adding both TXT and CNAME with same name

   • Impact: None (actually correct!)
   • Note: This is expected—TXT for verification, CNAME for traffic

2. Orange cloud too soon (Cloudflare)

   • Impact: May prevent connections or cause SSL errors
   • Fix: Use gray cloud until working

3. Pointing to wrong edge region

   • Impact: Higher latency or failures
   • Fix: Use exact CNAME target from Jetty

4. Not removing old records

   • Impact: Traffic goes to old destination
   • Fix: Delete/replace existing records first

Validation: Manual confirmation that CNAME/A record is added

Step 8: Create Tunnel with Custom Domain

Duration: ~45 seconds

Users learn to create tunnels using their verified custom domain via CLI or dashboard.

CLI Examples

# Auto-detect port with custom domain
jetty share --subdomain api.example.com

# Specific port with custom domain
jetty share 3000 --subdomain api.example.com

# Local HTTPS (port 443) with custom domain
jetty share 443 --subdomain api.example.com

# Use domain from config file
jetty share  # if custom_domain set in ~/.jetty/config.json

Dashboard Alternative

Step-by-step instructions for creating tunnels via web UI:

1. Navigate to Tunnels
2. Click Create Tunnel
3. Select custom domain from dropdown
4. Configure settings
5. Create and test

Error Handling

Error: "Domain not found or not verified"

• Check dashboard domain status
• Verify correct account
• Check spelling

Error: "Connection refused"

• Local app not running
• Wrong port specified
• Firewall blocking

Error: "SSL certificate error"

• Certificate still provisioning (wait 1-2 min)
• Check dashboard shows "SSL: Active"

Validation: CLI-based check for tunnel creation

Step 9: Test Your Custom Domain Tunnel

Duration: ~60 seconds

Final verification that everything works end-to-end.

Testing Checklist

1. Domain resolves to correct page

• Browser loads local application
• Fail: DNS errors → wait for propagation

2. HTTPS is working

• Padlock icon shows secure connection
• Fail: Certificate warnings → wait for provisioning

3. All assets load correctly

• Images, CSS, JavaScript load
• Fail: Mixed content errors → check asset URLs

4. API requests work

• Test endpoints, forms, webhooks
• Fail: Use request inspector for debugging

5. WebSocket connections work (if applicable)

• Real-time features function
• Fail: Disable Cloudflare proxy temporarily

Browser-Based Testing

Basic Connectivity:

• Open DevTools (F12)
• Network tab
• Look for 200 OK responses
• Check for CORS/mixed content errors

SSL Certificate Validation:

• Click padlock icon
• View certificate details
• Verify Let's Encrypt issuer
• Confirm valid for your domain

Command-Line Testing

# Test basic connectivity
curl -I https://api.example.com

# Verbose SSL details
curl -v https://api.example.com

# Test API endpoints
curl https://api.example.com/api/users
curl -X POST https://api.example.com/api/login -d '{"email":"test@example.com"}'

Jetty Dashboard Inspection

Use built-in traffic inspection:

1. Go to Tunnels → Select your tunnel
2. Click "View Traffic" or "Request Inspector"
3. Make requests to your domain
4. Watch requests appear in real-time
5. Inspect headers, body, response

Benefits:

• Real-time request visibility
• Debug headers and payloads
• Share request links with team
• Identify errors immediately

Common Issues at Testing Phase

DNS_PROBE_FINISHED_NXDOMAIN:

• Meaning: DNS not propagated yet
• Solution: Wait 5-15 minutes, flush DNS cache

Certificate error/SSL warning:

• Meaning: Certificate still provisioning
• Solution: Wait 1-2 minutes, check dashboard status

502 Bad Gateway or 503:

• Meaning: Can't reach local application
• Solution: Verify app running, tunnel connected, test locally

Assets don't load:

• Meaning: Mixed content or incorrect URLs
• Solution: Check console, use relative URLs, set APP_URL

WebSockets don't connect:

• Meaning: WebSocket upgrade blocked
• Solution: Disable Cloudflare proxy, check Jetty plan supports WS

Validation: Manual confirmation that tunnel works

Pain Points Addressed

1. DNS Propagation Delays

Problem: Users expect instant DNS updates but propagation can take minutes to hours.

Solution:

• Set realistic expectations with provider-specific timelines
• Teach multiple checking methods (dig, nslookup, online tools)
• Explain what affects propagation (TTL, provider, caching)
• Provide "be patient" messaging to reduce frustration

2. DNS Record Format Confusion

Problem: Different DNS providers use different formats for record names.

Solution:

• Show all common format variations up front
• Provider-specific instructions with exact field names
• Examples for each major provider
• "Don't worry about format" reassurance

3. Cloudflare Proxy Issues

Problem: Orange cloud (proxy mode) can interfere with TXT verification and initial tunnel setup.

Solution:

• Explicit warning about gray cloud vs orange cloud
• Explain when to use each mode
• Provider-specific callouts in multiple steps
• Visual cues (cloud icon references)

4. Copy-Paste Errors

Problem: Missing characters, extra spaces, or truncated values cause verification failures.

Solution:

• Emphasize copying the ENTIRE value
• Warn about spaces and line breaks
• Explain that case doesn't matter (reduce anxiety)
• Provide character-by-character comparison advice

5. Root Domain vs Subdomain Confusion

Problem: Users don't understand implications of using root domain for tunnels.

Solution:

• Clear recommendation: use subdomains
• Explain why (flexibility, no conflicts)
• Show good vs bad examples with reasons
• Warn about root domain limitations

6. SSL Certificate Timing

Problem: Users try to use domain immediately after verification, before certificate is ready.

Solution:

• Explain 1-2 minute provisioning time
• Set expectations for "Certificate Provisioning" status
• Include certificate checks in testing phase
• Provide troubleshooting if certificate fails

7. Multiple Service Confusion

Problem: Users have TXT records for other services (Google, Microsoft, etc.) and worry about conflicts.

Solution:

• Explain multiple TXT records are normal and safe
• Show that _jetty-verification prefix prevents conflicts
• Reassure that other services won't be affected

8. Lack of Verification Tools

Problem: Users don't know how to check if DNS changes worked.

Solution:

• Teach four different checking methods
• Command-line tools for technical users
• Web-based tools for non-technical users
• Expected output and interpretation for each

9. Error Message Ambiguity

Problem: Generic error messages don't help users fix issues.

Solution:

• Specific error explanations for each type
• "What this means" plain-language descriptions
• Multiple solution options for each error
• Links to relevant documentation sections

10. Testing Uncertainty

Problem: Users don't know if setup worked correctly.

Solution:

• Comprehensive testing checklist
• Multiple testing methods (browser, curl, dashboard)
• Clear success criteria
• Common issues at testing phase with solutions

Implementation Notes

Tutorial Definition

The tutorial is defined in custom-domain-setup.json with the following structure:

{
  "id": "custom-domain-setup",
  "version": "1.0.0",
  "title": "Setting Up Your First Custom Domain",
  "steps": [ /* 9 steps with detailed content */ ],
  "prerequisites": { /* plan, features, knowledge */ },
  "validation": { /* per-step validation rules */ }
}

Validation Types

Each step uses different validation mechanisms:

• Route-based: Checks user is on correct dashboard page
• Input-based: Confirms domain was submitted
• Interaction: Tracks user viewed verification record
• Manual: User confirms action completed
• Status: Checks backend domain verification status
• CLI: Detects tunnel creation with custom domain

Provider-Specific Data Structure

DNS providers are structured with:

{
  "name": "Provider Name",
  "popularity": "high|medium|low",
  "instructions": [ /* step-by-step array */ ],
  "commonIssues": [
    {
      "issue": "Description",
      "impact": "What happens",
      "solution": "How to fix"
    }
  ],
  "verificationUrl": "https://provider.com"
}

This allows the UI to:

• Sort by popularity
• Filter by user's provider
• Show provider-specific warnings
• Link directly to provider's DNS settings

Troubleshooting Resources

The tutorial links to comprehensive documentation:

• DNS Propagation Delays
• Common DNS Errors
• Certificate Issues
• Using dig/nslookup
• Custom Domains User Guide
• CLI Usage Guide
• Traffic Inspection Guide

Completion and Next Steps

Upon completion:

• User receives "custom-domain-expert" badge
• Suggested next tutorials: traffic inspection, webhook testing, team collaboration
• Links to advanced topics: wildcard domains, multiple subdomains, APEX setup

Best Practices

For Tutorial Maintainers

1. Keep Provider Instructions Updated: DNS providers change their UIs frequently
2. Monitor Support Tickets: Add common issues to troubleshooting sections
3. Test Propagation Times: Verify time estimates remain accurate
4. Update SSL Details: Keep Let's Encrypt information current
5. Add New Providers: Include popular providers as they emerge

For Content Writers

1. Use Plain Language: Avoid jargon where possible, explain when necessary
2. Show, Don't Just Tell: Include examples, expected output, visual guides
3. Anticipate Confusion: Address questions before users ask them
4. Provide Multiple Paths: Command-line AND web-based tools
5. Be Encouraging: DNS setup is frustrating; acknowledge and encourage

For Developers

1. Graceful Degradation: Tutorial should work even if some features unavailable
2. Progress Persistence: Save progress so users can resume
3. Skip Options: Let advanced users skip steps they've completed
4. Real-Time Validation: Check domain status via API, don't rely on manual confirmation alone
5. Error Recovery: Allow users to go back and fix mistakes

Metrics to Track

Completion Metrics

• Overall completion rate
• Drop-off point analysis (which step users abandon)
• Time spent per step vs estimates
• Total time from start to finish

Error Metrics

• Most common errors encountered
• Error frequency per step
• Retry attempts per error type
• Support ticket correlation

User Behavior

• Provider distribution (most common DNS providers)
• Subdomain vs root domain choices
• CLI vs dashboard usage
• Browser vs command-line testing preference

Success Metrics

• Successful verification rate (first attempt)
• Average propagation time by provider
• Tunnel creation success rate
• SSL certificate provisioning success rate

Future Enhancements

Phase 1: Intelligence

• Provider Detection: Auto-detect user's DNS provider from domain
• Propagation Prediction: Estimate wait time based on provider and TTL
• Proactive Checking: Poll DNS in background, notify when ready

Phase 2: Automation

• API Integration: Direct integration with Cloudflare API for one-click setup
• Record Validation: Check record format before user leaves dashboard
• Automated Testing: Run connectivity tests automatically

Phase 3: Advanced Features

• Video Walkthroughs: Short videos for visual learners
• Live Chat Integration: Context-aware help during tutorial
• Provider-Specific Tutorials: Separate flows optimized per provider

Related Documentation

• Custom Domains User Guide: Comprehensive reference documentation
• CLI Usage Guide: CLI command reference
• Traffic Inspection Guide: Debugging tunnel traffic
• DNS Provider Examples: Detailed provider instructions
• Verification Troubleshooting: Common issues and solutions

Support Resources

If users encounter issues not covered by the tutorial:

1. Documentation: Check the Custom Domains user guide
2. Community: Ask in Jetty community forums or Discord
3. Support: Contact Jetty support with domain name and error details
4. Status Page: Check if there are known DNS or certificate issues

Conclusion

This tutorial transforms the complex, error-prone process of custom domain setup into a guided, educational experience. By anticipating pain points, providing provider-specific guidance, and teaching troubleshooting skills, it empowers users to successfully configure custom domains with confidence.

The investment in comprehensive content pays dividends in reduced support burden, increased feature adoption, and improved user satisfaction with a traditionally frustrating setup process.