Scaling SaaS Multi-Tenant Custom Domains: A Guide to Implementing Caddy Server v2 with On-Demand TLS

Introduction to the Multi-Tenant Custom Domain Challenge

For modern Software-as-a-Service (SaaS) platforms, offering multi-tenancy is standard practice. Users typically access their dashboards or white-labeled sites via subdomains like tenant.saasplatform.com. However, as these platforms scale, enterprise clients increasingly demand the ability to use their own branding through custom domains (e.g., [www.clientdomain.com](https://www.clientdomain.com)).

Historically, provisioning SSL/TLS certificates for thousands of external custom domains was a logistical nightmare for engineering teams. Traditional approaches involving cron jobs, Let's Encrypt rate limits, and complex Nginx configurations often led to fragile infrastructure and delayed domain activation. This is where Caddy Server v2 and its revolutionary On-Demand TLS feature become a game-changer for SaaS architecture.

Understanding Caddy Server v2 and On-Demand TLS

Caddy v2 is a modern, open-source web server written in Go, celebrated for its automatic HTTPS capabilities. Unlike traditional web servers that require certificates to be pre-configured and loaded into memory before traffic arrives, Caddy introduces On-Demand TLS.

With On-Demand TLS, Caddy does not obtain an SSL certificate when the server starts. Instead, it defers certificate generation to the exact moment a user makes the first TLS handshake request to a custom domain. If a certificate is missing or expired, Caddy communicates with Let's Encrypt or ZeroSSL in real-time, provisions the certificate within seconds, completes the handshake, and caches it for future use. This significantly reduces upfront operational overhead and eliminates configuration reloads.

Architecture Blueprint for SaaS Custom Domains

To implement this securely, you cannot allow Caddy to issue certificates for any random domain pointing to your server, as malicious actors could exhaust your rate limits or fill your storage. You must establish an architectural workflow with an internal approval mechanism.

• DNS Routing: The customer configures a CNAME record pointing their custom domain to your SaaS routing endpoint (e.g., cname.saasplatform.com).
• The Caddy Edge Proxy: Caddy sits at the perimeter, intercepting incoming HTTPS traffic.
• The Verification API: When a new domain hits Caddy, Caddy makes an internal HTTP call to your backend application to verify if this specific domain is registered and active in your database.
• The Upstream Application: Once verified and secured, Caddy proxies the request to your actual multi-tenant application service with the host headers intact.

Step-by-Step Implementation Guide

Step 1: Installing Caddy Server

First, ensure Caddy is installed on your edge server. For a production environment, deploying via official packages or utilizing a Docker container is highly recommended. Ensure your firewall allows traffic on ports 80 and 443.

Step 2: Building the Backend Verification Endpoint

Before configuring Caddy, your backend application must expose a secure, low-latency endpoint that Caddy can query during the TLS handshake. This endpoint must return an HTTP status code 200 OK if the domain is allowed to have a certificate, and a 400 or 404 if it is not.

Security Note: Optimize this endpoint using caching layers like Redis, as it will be hit on the very first request of every new custom domain connection.

Step 3: Configuring the Caddyfile

The Caddyfile is Caddy's human-readable configuration file. Below is a production-ready configuration designed for SaaS multi-tenancy utilizing On-Demand TLS:

{
    # Global options
    on_demand_tls {
        ask http://localhost:8000/api/v1/verify-domain
        interval 2m
        burst 5
    }
}

# Handle all incoming HTTPS traffic dynamically
:443 {
    tls {
        on_demand
    }

    # Proxy traffic to your internal backend application
    reverse_proxy [http://127.0.0.1:3000](http://127.0.0.1:3000) {
        header_up Host {header.Host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
    }
}

In this configuration, the ask parameter tells Caddy to send a GET request to http://localhost:8000/api/v1/verify-domain?domain=clientdomain.com before attempting to fetch a certificate. The interval and burst parameters act as rate limiters to protect your infrastructure from denial-of-service attempts.

Critical Security and Production Considerations

While Caddy simplifies SSL management, deploying it at scale requires adherence to strict production best practices:

1. Storage Management

Caddy saves certificates to the local file system by default. In a high-availability setup with multiple clustered Caddy instances behind a cloud load balancer, you must use a shared storage plugin (such as Redis, S3, or PostgreSQL) so all instances share the same certificate pool and avoid hitting Let's Encrypt rate limits independently.

2. Rate Limiting and Monitoring

Implement strict rate limits on your verification endpoint. Monitor Caddy logs closely for failed handshakes, which might indicate misconfigured customer DNS records or malicious automated scanning.

3. Graceful Handling of Unregistered Domains

Ensure your backend application responds swiftly to the ask endpoint. If your database or cache goes down, ensure your system fails securely by rejecting unknown domain requests rather than allowing open certificate generation.

Conclusion

Implementing Caddy Server v2 with On-Demand TLS transforms how SaaS platforms handle multi-tenant custom domains. It shifts the burden of certificate lifecycle management from complex devops automation scripts directly to the edge web server, providing a seamless, instant-on experience for your end users. By coupling Caddy's native capabilities with a robust backend verification system, you build a scalable, secure, and enterprise-ready branding solution for your platform.