Jetty

Documentation for Jetty

Custom Domains

Overview

Custom domains allow you to use your own domain name (e.g., api.example.com) for your Jetty tunnels instead of the default *.tunnels.usejetty.online subdomain. This provides a more professional appearance and allows you to maintain consistent branding across your development and staging environments.

Why Use Custom Domains?

  • Professional Branding: Use your company's domain instead of generic tunnel URLs
  • Consistent URLs: Keep the same domain when sharing with clients, QA teams, or stakeholders
  • SSL/TLS Certificates: Jetty automatically provisions and renews SSL certificates for your custom domains
  • Production-like Environment: Test with URLs that match your production setup

How It Works

When you add a custom domain to Jetty:

  1. You verify domain ownership via DNS TXT record
  2. Jetty provisions an SSL/TLS certificate for your domain
  3. You can use the custom domain when creating or updating tunnels
  4. Traffic to your custom domain routes through Jetty's edge network to your local application

Prerequisites

Before adding a custom domain, ensure you have:

  • Paid Plan: Custom domains require a Coastal or Fleet plan (not available on Harbor free tier)
  • Domain Ownership: You must own or control the domain you want to use
  • DNS Access: Ability to add DNS records (TXT and CNAME/A records) at your domain registrar or DNS provider
  • Active Jetty Account: A logged-in account with appropriate plan subscription

Adding a Custom Domain

Step 1: Navigate to Custom Domains

  1. Log in to the Jetty Dashboard
  2. Click on Settings in the left sidebar
  3. Select the Custom Domains tab
  4. Click the Add Domain button

Step 2: Enter Your Domain

  1. In the "Add Custom Domain" dialog, enter your domain or subdomain
  2. Examples:
    • api.example.com (subdomain)
    • tunnel.mycompany.dev (subdomain)
    • example.com (root domain - not recommended for tunnels)
  3. Click Continue

Best Practice: Use a subdomain (like dev.example.com or tunnel.example.com) rather than your root domain. This gives you flexibility and prevents conflicts with your main website.

Step 3: DNS Verification

After submitting your domain, Jetty will generate a unique verification TXT record.

Copy the Verification Record

You'll see a screen showing:

Name:  _jetty-verification.api.example.com
Type:  TXT
Value: jetty-verify-abc123def456xyz789

Important: Keep this page open or copy these values somewhere safe. You'll need them in the next step.

Add the TXT Record to Your DNS Provider

  1. Open a new tab and log in to your DNS provider (see provider-specific instructions below)
  2. Navigate to the DNS management section for your domain
  3. Add a new TXT record with the provided name and value
  4. Save the record

Note: DNS propagation can take anywhere from a few minutes to 48 hours, though it's typically faster (5-30 minutes).

Verify the Domain

  1. Return to the Jetty Dashboard
  2. Click Verify Domain or Check Verification Status
  3. Jetty will query DNS for the TXT record
  4. If found, your domain status will change to "Verified"

Once verified, Jetty automatically provisions an SSL/TLS certificate for your domain (this usually takes 1-2 minutes).

Step 4: Point Your Domain to Jetty

After verification, you need to point your custom domain to Jetty's edge servers.

Jetty will provide you with either:

  • CNAME record: your-domain.tunnels.usejetty.online (recommended for subdomains)
  • A record(s): IP address(es) (for root domains)

Add this DNS record to your DNS provider:

For subdomains (recommended):

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

For root domains:

Name:  example.com
Type:  A
Value: 203.0.113.10

Step 5: Use with Tunnels

Once your domain is verified and pointed to Jetty, you can use it when creating or sharing tunnels.

Using the CLI

When starting a tunnel with jetty share, specify your custom domain:

jetty share --subdomain api.example.com

Or for port-specific sharing:

jetty share 8080 --subdomain api.example.com

Using the Dashboard

  1. Go to Tunnels in the dashboard
  2. Click Create Tunnel or edit an existing tunnel
  3. In the domain field, select your custom domain from the dropdown
  4. Click Save or Create

Your tunnel will now be accessible at your custom domain with automatic HTTPS!

DNS Provider Examples

Cloudflare

Cloudflare is a popular DNS provider and CDN service.

Adding TXT Record for Verification

  1. Log in to Cloudflare Dashboard
  2. Select your domain from the list
  3. Click on the DNS tab
  4. Click Add record
  5. Configure the record:
    • Type: TXT
    • Name: _jetty-verification.api (if your full domain is api.example.com)
    • Content: Paste the verification token from Jetty
    • TTL: Auto or 1 hour
    • Proxy status: DNS only (gray cloud)
  6. Click Save

Adding CNAME Record

  1. Click Add record again
  2. Configure the record:
    • Type: CNAME
    • Name: api (for api.example.com)
    • Target: custom.tunnels.usejetty.online
    • TTL: Auto
    • Proxy status: DNS only (gray cloud - important!)
  3. Click Save

Important: Disable Cloudflare's proxy (use "DNS only" gray cloud) for Jetty custom domains. The orange cloud proxies traffic through Cloudflare, which can interfere with WebSocket connections and tunnel functionality.

![Cloudflare DNS Settings - Screenshot Placeholder]

AWS Route 53

Amazon Route 53 is AWS's DNS service.

Adding TXT Record for Verification

  1. Open the Route 53 Console
  2. Click Hosted zones in the left navigation
  3. Select your domain's hosted zone
  4. Click Create record
  5. Configure the record:
    • Record name: _jetty-verification.api
    • Record type: TXT
    • Value: Paste the verification token (include quotes)
    • TTL: 300 seconds
    • Routing policy: Simple routing
  6. Click Create records

Adding CNAME Record

  1. Click Create record again
  2. Configure the record:
    • Record name: api
    • Record type: CNAME
    • Value: custom.tunnels.usejetty.online
    • TTL: 300 seconds
  3. Click Create records

![AWS Route 53 DNS Settings - Screenshot Placeholder]

Google Cloud DNS

Google Cloud DNS is Google's scalable DNS service.

Adding TXT Record for Verification

  1. Open the Cloud DNS Console
  2. Click on your DNS zone
  3. Click Add record set
  4. Configure the record:
    • DNS name: _jetty-verification.api.example.com. (note the trailing dot)
    • Resource record type: TXT
    • TTL: 5 minutes
    • TXT data: Paste the verification token (include quotes)
  5. Click Create

Adding CNAME Record

  1. Click Add record set again
  2. Configure the record:
    • DNS name: api.example.com.
    • Resource record type: CNAME
    • TTL: 5 minutes
    • Canonical name: custom.tunnels.usejetty.online.
  3. Click Create

Other DNS Providers

The process is similar for other providers:

  • Namecheap: Advanced DNS → Add New Record
  • GoDaddy: DNS Management → Add → TXT/CNAME
  • DigitalOcean: Networking → Domains → Add Record
  • Vercel: Domains → DNS Records
  • Netlify: Domain settings → DNS panel

Consult your provider's documentation for specific instructions.

Verification Troubleshooting

"Verification Pending" Stuck

If your domain verification status remains "Pending" for more than 30 minutes:

  1. Check DNS propagation: Use the diagnostic tools below
  2. Verify the TXT record value: Ensure you copied the entire token without extra spaces
  3. Check the record name: Confirm the _jetty-verification prefix is correct
  4. Wait longer: DNS propagation can take up to 48 hours (though usually much faster)
  5. Contact support: If still stuck after 24 hours

DNS Propagation Delays

DNS changes don't happen instantly. Factors affecting propagation time:

  • TTL (Time To Live): Lower TTL = faster updates (but more frequent lookups)
  • DNS provider: Some providers propagate faster than others
  • ISP caching: Your internet provider may cache old DNS records
  • Global distribution: Records must propagate to DNS servers worldwide

Patience is key: Most DNS changes propagate within 5-30 minutes, but allow up to 24 hours.

Common DNS Errors

Error: "TXT record not found"

Cause: The DNS record hasn't been added or hasn't propagated yet.

Solution:

  1. Double-check you added the record at your DNS provider
  2. Verify the record name includes _jetty-verification prefix
  3. Wait 15-30 minutes and try verification again
  4. Use dig or online tools to check if the record exists

Error: "TXT record value mismatch"

Cause: The TXT record value doesn't match what Jetty expects.

Solution:

  1. Copy the verification token again from the Jetty dashboard
  2. Check for extra spaces or missing characters
  3. Ensure you didn't paste it multiple times or include quotes (unless required by your DNS provider)
  4. Update the DNS record and wait for propagation

Error: "Domain already in use"

Cause: Another Jetty user has already verified this domain.

Solution:

  • If you own the domain, someone else may have added it by mistake
  • Contact Jetty support to resolve ownership
  • Use a different subdomain

Error: "Invalid domain format"

Cause: The domain name format is incorrect.

Solution:

  • Use proper format: subdomain.example.com or example.com
  • Don't include http://, https://, or trailing slashes
  • Avoid special characters (except hyphens)

Using dig/nslookup to Check DNS

You can check DNS records yourself using command-line tools.

Using dig (Mac/Linux)

Check the TXT verification record:

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

Expected output:

"jetty-verify-abc123def456xyz789"

Check the CNAME record:

dig api.example.com CNAME +short

Expected output:

custom.tunnels.usejetty.online.

Using nslookup (Windows/Mac/Linux)

Check the TXT record:

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

Check the CNAME record:

nslookup -type=CNAME api.example.com

Online DNS Checkers

If you don't have command-line tools available, use these online services:

These show DNS records from multiple global locations, helping you confirm propagation.

SSL/TLS Certificates

Jetty automatically handles SSL/TLS certificates for your custom domains, so you don't need to worry about certificate management.

How It Works

  1. Automatic Provisioning: When you verify a custom domain, Jetty requests an SSL certificate from Let's Encrypt
  2. Automatic Renewal: Certificates are automatically renewed before expiration (Let's Encrypt certificates are valid for 90 days)
  3. Secure Connection: All traffic to your custom domain uses HTTPS with strong encryption (TLS 1.2+)

Certificate Details

  • Issuer: Let's Encrypt Authority
  • Validity: 90 days (auto-renewed at 60 days)
  • Encryption: RSA 2048-bit or ECDSA P-256
  • Protocol: TLS 1.2 and TLS 1.3

Wildcard Certificates

If you use a wildcard custom domain (e.g., *.dev.example.com), Jetty provisions a wildcard certificate that covers all subdomains under that pattern.

Troubleshooting Certificate Issues

"Certificate not ready"

If you see this message:

  1. Wait 1-2 minutes for certificate provisioning to complete
  2. Verify your domain is fully verified (not pending)
  3. Check that DNS records point to Jetty

"Certificate error" in browser

If your browser shows a certificate warning:

  1. Verify the CNAME/A record points to Jetty correctly
  2. Check DNS propagation with dig or online tools
  3. Clear your browser cache and try again
  4. Wait a few more minutes for certificate propagation

Plan Limits

Custom domain availability depends on your Jetty plan:

Plan Custom Domains Price
Harbor 0 domains Free
Coastal 3 domains $9/month
Fleet 3 domains $29/month

Domain Count

  • Each verified domain counts toward your plan limit
  • Subdomains of the same root domain each count as separate domains:
    • api.example.com = 1 domain
    • staging.example.com = 1 domain (total: 2)
    • dev.example.com = 1 domain (total: 3)
  • Wildcard domains (if supported) count as 1 domain but can be used with multiple subdomains

Need More Domains?

If you need more than 3 custom domains:

  1. Upgrade to Fleet: Provides additional features beyond custom domains
  2. Use wildcard domains: One wildcard domain can cover many subdomains (see Advanced section)
  3. Contact sales: Enterprise plans can accommodate custom requirements

Removing Custom Domains

You can remove custom domains you no longer need, freeing up space for new domains.

Steps to Remove a Domain

  1. Go to Settings → Custom Domains in the Jetty dashboard
  2. Find the domain you want to remove
  3. Click the ⋮ (options) menu or Delete button
  4. Confirm the deletion

What Happens When You Remove a Domain

  • Domain verification is removed: You'll need to re-verify if you add it again later
  • Active tunnels using this domain will stop working: Update or remove affected tunnels first
  • SSL certificate is revoked: The certificate is no longer valid
  • DNS records remain: You must manually remove DNS records at your DNS provider
  • Domain limit decreases: You can now add a different domain

Before Removing

Check active tunnels: Make sure no active tunnels are using this domain, or they will become inaccessible.

# List all tunnels to check
jetty list

Update affected tunnels to use default Jetty domains or a different custom domain before removing.

Advanced Topics

Wildcard Domains

Wildcard domains allow you to use multiple subdomains under a single custom domain entry.

Example: *.dev.example.com covers:

  • api.dev.example.com
  • backend.dev.example.com
  • frontend.dev.example.com
  • Any other *.dev.example.com subdomain

Setting Up a Wildcard Domain

  1. Add the wildcard domain in Jetty: *.dev.example.com
  2. Complete DNS verification for _jetty-verification.dev.example.com (note: no asterisk)
  3. Add CNAME pointing *.dev.example.com to Jetty's edge servers
  4. Use any subdomain when creating tunnels: 
    jetty share --subdomain api.dev.example.com
jetty share --subdomain backend.dev.example.com

Limitations

  • Wildcards only work at one level (e.g., *.example.com doesn't cover a.b.example.com)
  • Some DNS providers don't support wildcard CNAME records
  • Count as 1 domain toward your plan limit

Multiple Subdomains

You can add multiple separate subdomains of the same root domain:

  • api.example.com (custom domain 1)
  • staging.example.com (custom domain 2)
  • dev.example.com (custom domain 3)

Each counts separately toward your plan limit (3 domains used in this example).

Alternative: Use a single wildcard domain *.example.com to cover all subdomains with only 1 domain slot.

APEX/Root Domain Setup

While possible, using root/apex domains (e.g., example.com without a subdomain) for tunnels is not recommended because:

  • May conflict with your main website
  • Some DNS providers don't support CNAME on apex domains
  • Requires A record, which can change if Jetty's infrastructure changes

Best practice: Always use a subdomain like tunnel.example.com or dev.example.com.

If you must use an apex domain:

  1. Check if your DNS provider supports ANAME or ALIAS records (recommended)
  2. Otherwise, use A records provided by Jetty
  3. Be prepared to update A records if notified by Jetty

Using Custom Domains with Teams

If you're on a team plan:

  • Custom domains belong to the team, not individual users
  • Team owners and admins can add/remove custom domains
  • All team members can use verified custom domains for their tunnels
  • Domain limits apply at the team level

Custom Domain Best Practices

  1. Use descriptive subdomains: api.dev.example.com is clearer than tunnel1.example.com
  2. Match your environment: Use subdomains that reflect the environment (dev, staging, demo)
  3. Document DNS changes: Keep track of DNS records you've added for future reference
  4. Test before sharing: Verify custom domain tunnels work before sharing with clients/team
  5. Monitor expiration: While Jetty auto-renews SSL, monitor domain registration expiration
  6. Use wildcard for flexibility: One wildcard domain provides maximum flexibility within limits
  7. Clean up unused domains: Remove domains you're no longer using to free up space

FAQ

Can I use the same custom domain on multiple tunnels?

No, each custom domain can only be assigned to one tunnel at a time. If you need multiple tunnels with custom domains, add multiple custom domains or use a wildcard domain with different subdomains.

Do I need to renew SSL certificates?

No, Jetty automatically provisions and renews SSL certificates for your custom domains. You don't need to do anything.

Can I use a custom domain from a different account?

No, you must verify domain ownership through DNS. You cannot use a domain verified by another Jetty account.

What happens if my DNS records change?

If you remove or modify the DNS records pointing to Jetty, your custom domain tunnel will stop working. Keep the CNAME/A records intact while using the domain with Jetty.

Can I transfer a custom domain to another Jetty account?

You must remove the domain from the first account, then add and verify it on the second account. The domain cannot be active on multiple accounts simultaneously.

Does this work with private tunnels?

Yes, custom domains work with both public and private tunnels. Authentication settings apply regardless of whether you're using a custom domain or default Jetty domain.

Getting Help

If you encounter issues not covered in this guide:

  1. Documentation: Check other Jetty guides and Getting Started
  2. Support: Email support@usejetty.online with:
    • Your custom domain
    • Error messages
    • DNS records (screenshot or dig/nslookup output)
    • Steps you've tried
  3. Community: Join the Jetty Discord or community forums
  4. Status page: Check status.usejetty.online for service issues

Next Steps:

Send feedback

Found an issue or have a suggestion? Let us know.