Custom Domains

The Problem

SaaS platforms often need to let customers use their own domain names (e.g., docs.acme.com instead of acme.yourapp.com). This requires DNS verification to prove domain ownership, automatic TLS certificate provisioning so HTTPS works seamlessly, and a reverse proxy layer that routes incoming requests to the correct tenant. The system must handle certificate renewal, DNS propagation delays, domain conflicts, and the operational complexity of managing thousands of certificates across a fleet of edge servers.

Architectural Approaches

Architecture

Loading diagram...

Key Components

Data Model

Loading diagram...

DNS Verification Flow

Before provisioning a TLS certificate, you must verify that the customer owns the domain. Two common methods:

DNS TXT Record Verification:

1. Generate a unique token: _yourapp-verify.customer.com TXT "v=yourapp1 token=abc123"
2. Customer adds the TXT record to their DNS
3. Your service periodically queries DNS for the record
4. Once found and matched, mark domain as verified
5. Customer then adds CNAME/A record pointing to your servers

HTTP Verification:

1. Generate a token and instruct customer to serve it at http://customer.com/.well-known/yourapp-verify
2. Your service makes an HTTP request to that URL
3. If the response contains the expected token, domain is verified

DNS propagation: TXT records can take 1-48 hours to propagate. Poll every 5 minutes for up to 72 hours before marking verification as failed. Show propagation status to the customer using multiple DNS resolver checks (Google 8.8.8.8, Cloudflare 1.1.1.1).

Loading diagram...

TLS Certificate Management at Scale

Managing thousands of TLS certificates introduces operational challenges:

Issuance: Let’s Encrypt rate limits to 50 certificates per registered domain per week. If you’re issuing certificates for customer.com subdomains, this is rarely a problem. But for high-volume onboarding, pre-warm by requesting certificates in advance or use multiple ACME accounts.

Storage: Private keys must be stored securely. Use a secrets manager (Vault, AWS Secrets Manager) with encryption at rest. Never store private keys in plain text in your database.

Distribution: When a certificate is issued or renewed, all reverse proxy instances need it. Options:

• Shared storage: All proxies read from a central store (S3, Vault). Adds latency on first request.
• Push distribution: Certificate provisioner pushes to all proxy instances via API. Faster but more complex.
• On-demand with caching: Proxy fetches certificate on first TLS handshake for a domain, caches locally. Caddy does this natively.

Renewal: Certificates expire in 90 days (Let’s Encrypt). Schedule renewal at 60 days. Run a daily cron job to renew certificates expiring within 30 days. Alert on any certificates expiring within 7 days as a safety net.

Revocation: When a customer removes their domain, revoke the certificate and remove it from all proxy instances. While not strictly necessary (it will expire naturally), it’s good hygiene.

Reverse Proxy Architecture

The reverse proxy is the critical path — every request flows through it.

Caddy is the top choice for custom domains because it has built-in ACME support, automatic HTTPS, and on-demand TLS certificate provisioning. It can request a certificate the first time a new domain hits the server.

Nginx with Lua modules (OpenResty) or dynamic certificate loading can also work but requires more custom code.

Certificate selection: During the TLS handshake, the client sends the domain name via SNI (Server Name Indication). The proxy uses this to select the correct certificate BEFORE the HTTP request is visible. This means certificate lookup must be fast — use an in-memory cache with the domain-to-certificate mapping.

Routing: After TLS termination, the proxy inspects the Host header and looks up the tenant in the routing table (Redis-cached). Routes to the correct tenant backend, injecting tenant context headers (X-Tenant-ID, X-Custom-Domain).

Fallback: If no certificate exists for a domain (new domain, not yet provisioned), serve a branded landing page explaining setup is in progress. Never show a browser certificate error.

Real-World Examples

Architectural Tradeoffs

# Learn the System Design of: Custom Domains

You are an expert software architect and teacher. I want to understand custom domains as a practical system design capability. (Let users map their own domains to your SaaS with DNS verification and automatic TLS).

Use the following architectural guide as a learning reference. Avoid one-size-fits-all recommendations. Keep assumptions, costs, and tradeoffs explicit.

---

import { Mermaid, ComponentList, ComponentCard, ApproachList, Approach, Example, Tradeoff } from '@/components/mdx';

## The Problem

SaaS platforms often need to let customers use their own domain names (e.g., docs.acme.com instead of acme.yourapp.com). This requires DNS verification to prove domain ownership, automatic TLS certificate provisioning so HTTPS works seamlessly, and a reverse proxy layer that routes incoming requests to the correct tenant. The system must handle certificate renewal, DNS propagation delays, domain conflicts, and the operational complexity of managing thousands of certificates across a fleet of edge servers.

## Architectural Approaches

<ApproachList>
<Approach
  name="Wildcard Certificate + CNAME"
  pros={[
    'Simple setup for subdomain-based tenants',
    'Single wildcard cert covers all subdomains',
    'CNAME setup is familiar to most users',
  ]}
  cons={[
    'Custom domains still need individual TLS certificates',
    'CNAME cannot be used at the zone apex (bare domain)',
    'DNS propagation can take hours — poor UX during setup',
  ]}
>
Issue a single wildcard certificate (*.yourapp.com) for your platform domain. Customers create a CNAME record pointing their domain to a dedicated endpoint (e.g., custom.yourapp.com). The reverse proxy inspects the Host header and routes to the correct tenant. For the customer's own domain, provision individual certificates via Let's Encrypt.
</Approach>
<Approach
  name="Automatic Certificate Provisioning with ACME"
  pros={[
    "Fully automated — zero manual certificate managem...

[Full prompt copied to clipboard]