1. Introduction: Caddy at Scale

Caddy is a modern, open-source web server written in Go that has fundamentally changed the way engineers think about web infrastructure. Unlike traditional web servers such as Nginx and Apache that require manual certificate management, complex configuration files, and extensive operational overhead, Caddy provides a radically simpler experience by offering automatic HTTPS out of the box. Since its initial release, Caddy has grown to become one of the most trusted web servers for teams that value developer experience, security defaults, and operational simplicity without sacrificing performance or flexibility. It powers millions of websites and has become a cornerstone of modern web infrastructure for solo developers, startups, and enterprise organizations alike.

The core philosophy behind Caddy is that encryption should not be optional or difficult. Every website served by Caddy automatically receives a valid TLS certificate from Let's Encrypt or ZeroSSL, with zero manual intervention. This is achieved through the ACME protocol (Automatic Certificate Management Environment), which Caddy implements natively and in full. The server handles the entire lifecycle of TLS certificates including issuance, renewal, revocation, and OCSP stapling transparently and reliably. This eliminates an entire class of operational bugs related to expired certificates, misconfigured certificate chains, and manual renewal scripts that plague organizations using traditional web servers. In a world where browsers mark HTTP sites as "Not Secure" and search engines penalize non-HTTPS sites, Caddy's automatic HTTPS is not just a convenience but a necessity for maintaining user trust and search engine rankings.

At scale, Caddy operates differently from its predecessors. It is built as a modular, pluggable system where every feature from TLS handling to logging to reverse proxying is implemented as a module. This module system means that Caddy's functionality can be extended without modifying the core binary, and configurations can be loaded dynamically at runtime through a powerful JSON-based configuration API. The admin API endpoint allows you to change Caddy's behavior without restarting the process, enabling zero-downtime reconfiguration in production environments. For senior engineers and architects, Caddy represents a paradigm shift in web server design. Instead of treating TLS as a bolt-on feature that requires separate tooling like certbot, acme.sh, or HAProxy's certificate management, Caddy treats it as a first-class citizen. The server understands the relationship between domain names and certificates natively, and it can provision certificates on-demand for any hostname that resolves to the server.

This on-demand TLS capability is particularly powerful for SaaS platforms and multi-tenant systems where you need to serve custom domains for hundreds or thousands of customers without pre-provisioning certificates. When designing a web server architecture around Caddy, there are several key considerations that senior engineers must address. First, understanding the module architecture is critical because it determines how requests flow through the server and how middleware is composed. Second, mastering both the Caddyfile and JSON configuration formats is essential, with the Caddyfile for its simplicity and readability and the JSON format for its completeness and API-driven capabilities. Third, understanding the ACME protocol internals, including how certificate challenges work via HTTP-01, TLS-ALPN-01, and DNS-01, enables you to design systems that work across complex network topologies including behind load balancers and in multi-server deployments.

In this comprehensive guide, we will dissect every aspect of Caddy's architecture and design. We will start from the foundational request handling pipeline, explore the configuration system in depth, understand how automatic HTTPS works under the hood, and then move into production-grade patterns for reverse proxying, load balancing, security hardening, and performance optimization. By the end of this article, you will have a thorough understanding of how to design, deploy, and operate Caddy as a production web server for modern applications. Whether you are running a simple static site, a complex microservices architecture, or a multi-tenant SaaS platform, Caddy provides the tools and abstractions necessary to build reliable, secure, and performant web infrastructure with significantly less operational complexity than traditional alternatives.

2. Core Architecture

Caddy's architecture is built around a concept called the caddyhttp module, which is the HTTP server implementation that handles all incoming HTTP and HTTPS requests. At its core, Caddy processes requests through a pipeline of handlers that are chained together. This pipeline is composed of listeners which accept connections, an HTTP server which parses requests, and a chain of middleware handlers that process each request sequentially. Understanding this architecture is fundamental to designing effective Caddy configurations and custom extensions. The architecture is designed around the principles of modularity, composability, and extensibility, allowing every component to be replaced or extended without modifying the core server logic.

The listener layer in Caddy is responsible for accepting incoming connections on specified network addresses and ports. Caddy supports multiple listeners simultaneously, each bound to different ports or network interfaces. When a connection arrives, the listener performs the TLS handshake if the connection is on a port configured for HTTPS. The TLS implementation in Caddy is built on Go's standard crypto/tls package with significant enhancements for OCSP stapling, certificate caching, and automatic certificate provisioning. Listeners can be configured to handle both HTTP/1.1 and HTTP/2 connections, and with Caddy v2.6 and later, HTTP/3 QUIC connections are supported natively through UDP listeners. The listener pool is managed internally by Caddy and supports dynamic reconfiguration when configurations change at runtime through the admin API.

Once a connection is established and TLS is negotiated if applicable, the request is passed to the HTTP server. The HTTP server parses the raw bytes into a structured HTTP request object and begins the routing process. Routing in Caddy is directive-based where each configuration block in a Caddyfile or each entry in the JSON configuration's routes array specifies a matcher and a handler. Matchers evaluate properties of the incoming request such as the path, host header, method, headers, query parameters, and more. When a matcher matches a request, the associated handler or chain of handlers is invoked. This matching system is highly efficient and designed for fast evaluation, using trie-based data structures internally for path matching.

The middleware chain is one of Caddy's most powerful architectural features. Middleware handlers are composable units of logic that can modify the request, short-circuit the chain by returning a response early, or pass the request to the next handler. Each middleware in the chain has access to the incoming request and a reference to the next handler in the chain. This design is similar to the chain-of-responsibility pattern and allows for extremely flexible request processing. For example, a typical request might flow through a headers middleware which sets security headers, then a rate limiter which may reject the request, then a reverse proxy which forwards the request to a backend, and finally back through the chain to send the response.

Directives and Their Priority

When using the Caddyfile format, directives are the high-level building blocks that map to specific handlers. Caddy processes directives in a predefined order, which is critical to understand because it determines the execution sequence of middleware. The directive order is explicitly defined in Caddy's source code and is designed to ensure that requests are processed correctly. For example, the bind directive is processed first to set the listener address, followed by tls to configure TLS, then root to set the file root, and so on through security-related directives, rewrite rules, file serving, and finally reverse proxying.

The matchers in Caddy are incredibly flexible and can be combined using logical operators. You can match on the request path using exact match, prefix match, regular expressions, or glob patterns, the Host header, HTTP method, request headers, query parameters, remote IP address, and even protocol such as HTTP versus HTTPS. Matchers can be ANDed together or ORed together, allowing you to create complex routing rules that precisely target specific requests. This matcher system replaces the complex location blocks found in Nginx configurations with a more composable and readable approach that is easier to understand and maintain.

Request Lifecycle in Detail

When a request enters Caddy's processing pipeline, it follows a well-defined lifecycle. First, the raw bytes are read from the connection and parsed into an HTTP request. Second, the request is matched against all configured routes in order. Each route contains one or more matcher sets and a handler chain. If a matcher set matches the request, the associated handler chain is invoked. Third, the handler chain executes middleware in order, with each middleware having the opportunity to modify the request, write the response, or call the next handler. Fourth, the terminal handler, typically a reverse proxy or file server, generates the response. Fifth, the response passes back through the middleware chain in reverse order, allowing each middleware to modify the response headers or body. Finally, the response is written to the client connection.

This architecture makes Caddy extremely predictable and debuggable. When you understand the directive order, the matcher system, and the middleware chain, you can precisely control how every request is processed. The modular design also means that you can replace any handler in the chain with a custom implementation, enabling Caddy to be extended for virtually any use case without forking the core codebase. The lifecycle is deterministic and well-documented, making it straightforward to reason about request flow even in complex configurations with many middleware layers. This predictability is a significant advantage when debugging production issues or designing complex routing logic.

3. Caddyfile Configuration

The Caddyfile is Caddy's human-readable configuration format, designed for simplicity and ease of use. It was created to make web server configuration accessible to developers who do not want to learn a complex configuration language. While the Caddyfile is a simplified configuration format that compiles down to the full JSON configuration, it covers the vast majority of use cases and is the recommended starting point for most deployments. The Caddyfile syntax is inspired by but distinct from Nginx's configuration format, with a focus on clarity and minimalism. The design philosophy is that configuration should be self-documenting, meaning that someone reading the Caddyfile should be able to understand what it does without consulting external documentation.

A Caddyfile is structured around site blocks, which define the configuration for specific addresses or domain names. Each site block contains directives that configure how requests to that address should be handled. Directives are keywords that Caddy recognizes, and each directive maps to a specific handler module. The Caddyfile is parsed and compiled into Caddy's internal JSON representation before the server starts, which means it has access to all of Caddy's features, though some advanced configurations may require the JSON format directly.

Caddyfile
# Global options block
{
    email admin@example.com
    admin :2019
    log {
        output file /var/log/caddy/access.log
        format json
    }
    on_demand_tls {
        ask http://localhost:3000/api/check-domain
    }
}

# Site block for main domain
example.com {
    root * /var/www/html
    encode gzip zstd
    tls {
        protocols tls1.2 tls1.3
        ciphers TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256
    }
    header {
        X-Content-Type-Options nosniff
        X-Frame-Options DENY
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"
        -Server
    }
    log {
        output file /var/log/caddy/example.log
        format json
    }
    reverse_proxy localhost:8080 {
        health_uri /health
        health_interval 10s
        health_timeout 5s
        lb_policy round_robin
        fail_duration 30s
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
    }
}

# API subdomain
api.example.com {
    reverse_proxy localhost:3001 {
        header_up Authorization {header.Authorization}
    }
    log {
        output file /var/log/caddy/api.log
    }
}

The global options block, enclosed in curly braces at the top of the Caddyfile, configures server-wide settings that apply across all site blocks. The email directive sets the email address used for ACME account registration with Let's Encrypt. The admin directive configures the admin API endpoint, which allows runtime configuration changes. The log directive sets up global logging with the specified output destination and format. The on_demand_tls directive enables on-demand certificate provisioning and specifies an endpoint that Caddy should query to verify whether a domain should receive a certificate.

Matchers in the Caddyfile

Matchers in the Caddyfile are specified using a compact syntax that precedes the handler directive. For example, to apply a directive only to requests matching a specific path, you would use the @name syntax to define a named matcher and then reference it. The available matcher types include path for URL path matching, header for request header matching, method for HTTP method matching, query for query parameter matching, remote_ip for client IP matching, protocol for HTTP and HTTPS matching, and host for hostname matching. These matchers can be combined within a single named matcher definition to create precise request filters.

Caddyfile
example.com {
    # Named matcher for API v2 endpoints
    @apiv2 {
        path /api/v2/*
        header Authorization Bearer *
    }
    reverse_proxy @apiv2 localhost:8082

    # Named matcher for WebSocket connections
    @websocket {
        header Connection *Upgrade*
        header Upgrade websocket
    }
    reverse_proxy @websocket localhost:8081

    # Named matcher for POST requests to /submit
    @submit {
        method POST
        path /submit
    }
    reverse_proxy @submit localhost:8083

    # Catch-all: serve static files
    file_server
}

The matcher syntax is incredibly powerful. When you specify multiple conditions within a single named matcher, they are ANDed together meaning all conditions must match for the request to be routed to the associated handler. This makes it straightforward to create complex routing rules. For example, the @apiv2 matcher above will only match requests that both have a path starting with /api/v2/ AND have an Authorization header starting with Bearer. If you need OR semantics, you can use the @name syntax multiple times with the same name, and Caddy will treat them as alternatives.

Tokens and Parsing

The Caddyfile parser breaks the configuration into tokens, which are individual units of text that are parsed into structured configuration. Tokens are separated by whitespace, and the parser understands several syntactic constructs: bare words like reverse_proxy, quoted strings like "max-age=31536000", blocks enclosed in curly braces, and subdirectives which are directive-specific arguments. The parser also supports comments using the # character, which are ignored during parsing. Understanding the tokenization process is important when debugging Caddyfile parsing errors, as the error messages typically reference token positions and types.

One of the most elegant aspects of the Caddyfile is how it maps to the JSON configuration. Every Caddyfile is first compiled into a complete JSON representation, which is then processed by Caddy's module system. This means that the Caddyfile is not a separate configuration language but rather a syntactic sugar layer on top of the JSON configuration. This design has several benefits: it ensures that the Caddyfile always has access to all of Caddy's features since the JSON format is the complete configuration, it simplifies the Caddy implementation since there is only one configuration format internally, and it allows users to seamlessly transition from the Caddyfile to the JSON format when they need advanced features that do not have Caddyfile syntax equivalents.

When working with the Caddyfile in production, there are several best practices to follow. First, always use named matchers for complex routing rules, as they improve readability and make configurations easier to maintain. Second, leverage the import directive to split large Caddyfiles into smaller, more manageable files, which is particularly useful when managing configurations for multiple sites. Third, use the caddy validate command to check your configuration for errors before deploying it, and the caddy fmt command to automatically format your Caddyfile for consistency. Fourth, consider using environment variables in your Caddyfile via the {$VARIABLE_NAME} syntax to make configurations portable across environments without requiring template processing.

4. JSON Configuration (API-driven, Dynamic Configuration)

The JSON configuration format is Caddy's complete, unfiltered configuration representation. While the Caddyfile is designed for human readability and covers common use cases, the JSON format provides full access to every configuration option, module, and parameter available in Caddy. This makes the JSON format essential for advanced deployments, programmatic configuration, and scenarios where configurations need to be generated or modified dynamically at runtime. The JSON configuration is also the format used by Caddy's admin API, which means understanding it is crucial for managing Caddy in production environments where configurations change frequently.

A Caddy JSON configuration is a single JSON object that specifies one or more apps, which are top-level modules that provide major functionality. The most common apps are http for the HTTP server, tls for TLS certificate management, logging for the logging subsystem, and pki for internal PKI used in client authentication. Each app has its own configuration schema defined by its module, and Caddy validates the configuration against these schemas when loading it. The modular design means that adding new apps or extending existing ones is as simple as writing a Go module that implements the caddy.App interface.

JSON (Caddy configuration)
{
    "apps": {
        "http": {
            "servers": {
                "production": {
                    "listen": [":443", ":80"],
                    "routes": [
                        {
                            "match": [
                                {
                                    "host": ["example.com", "www.example.com"],
                                    "path": ["/api/*"]
                                }
                            ],
                            "handle": [
                                {
                                    "handler": "reverse_proxy",
                                    "upstreams": [
                                        {"dial": "localhost:8080"},
                                        {"dial": "localhost:8081"}
                                    ],
                                    "load_balancing": {
                                        "selection_policy": {
                                            "policy": "round_robin"
                                        }
                                    },
                                    "health_checks": {
                                        "active": {
                                            "uri": "/health",
                                            "interval": "10s",
                                            "timeout": "5s"
                                        }
                                    }
                                }
                            ]
                        },
                        {
                            "match": [{"host": ["example.com"]}],
                            "handle": [
                                {
                                    "handler": "file_server",
                                    "root": "/var/www/html",
                                    "browse": {}
                                }
                            ]
                        }
                    ],
                    "automatic_https": {
                        "issuers": [
                            {
                                "email": "admin@example.com"
                            }
                        ]
                    }
                }
            }
        },
        "tls": {
            "automation": {
                "policies": [
                    {
                        "issuers": [
                            {
                                "module": "acme",
                                "challenges": {
                                    "http": {}
                                }
                            }
                        ]
                    }
                ]
            }
        }
    }
}

The admin API is Caddy's built-in HTTP server that runs on a separate port, defaulting to localhost:2019, and provides RESTful endpoints for managing Caddy's configuration at runtime. The primary endpoint is POST /load, which accepts a complete JSON configuration and atomically replaces the running configuration. This means you can change Caddy's entire configuration without restarting the process, and Caddy handles graceful transitions where existing connections are served using the old configuration while new connections use the new configuration.

The configuration change process in Caddy is atomic and transactional. When you POST a new configuration to the admin API, Caddy first validates the entire configuration against the loaded modules' schemas. If validation passes, Caddy prepares the new configuration internally, including creating new listener pools, establishing new backend connections for reverse proxies, and provisioning new TLS certificates if needed. Only when all preparations are complete does Caddy atomically switch to the new configuration. This ensures that there is no intermediate state where the configuration is partially applied, which could lead to inconsistent behavior or downtime.

A common pattern in production is to use a separate configuration management service that generates Caddy JSON configurations and pushes them to Caddy's admin API. For example, in a Kubernetes environment, an operator watches for Ingress resources and translates them into Caddy configurations, which are then pushed to Caddy's admin API whenever an Ingress is created, updated, or deleted. This approach combines the power of Kubernetes-native resource management with Caddy's dynamic configuration capabilities, eliminating the need for a separate ingress controller binary while providing all the features needed for production traffic management.

C# (Admin API interaction pattern)
// Pattern for dynamically managing Caddy via Admin API
public class CaddyConfigManager
{
    private readonly HttpClient _httpClient;
    private readonly string _adminEndpoint;

    public CaddyConfigManager(string adminEndpoint)
    {
        _adminEndpoint = adminEndpoint;
        _httpClient = new HttpClient
        {
            BaseAddress = new Uri(adminEndpoint)
        };
    }

    public async Task LoadConfigurationAsync(CaddyConfig config)
    {
        var json = JsonSerializer.Serialize(config, new JsonSerializerOptions
        {
            PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
            DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull
        });

        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await _httpClient.PostAsync("/load", content);
        response.EnsureSuccessStatusCode();
    }

    public async Task AddUpstreamAsync(string routePath, string upstreamDial)
    {
        var path = $"config/apps/http/servers/srv0/routes/{routePath}/handle/0/upstreams";
        var upstream = JsonSerializer.Serialize(new { dial = upstreamDial });
        var content = new StringContent(upstream, Encoding.UTF8, "application/json");
        var response = await _httpClient.PostAsync($"/config/{path}", content);
        response.EnsureSuccessStatusCode();
    }

    public async Task<CaddyConfig> GetCurrentConfigAsync()
    {
        var response = await _httpClient.GetAsync("/config/");
        response.EnsureSuccessStatusCode();
        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<CaddyConfig>(json);
    }
}

When designing systems around Caddy's dynamic configuration, it is important to consider the concurrency model. Multiple clients can attempt to modify the configuration simultaneously, and Caddy handles this by processing configuration changes sequentially. Each request to /load or /config/{path} is processed one at a time, ensuring that there are no race conditions in configuration application. However, this also means that long-running configuration operations such as provisioning TLS certificates for multiple domains can block subsequent configuration changes. In high-throughput environments, it is advisable to batch configuration changes and use the incremental API for small, frequent changes while reserving the full /load endpoint for major configuration overhauls. This design choice prioritizes correctness and simplicity over concurrent throughput, which is appropriate for a configuration management API where consistency is paramount.

5. Automatic HTTPS (ACME/Let's Encrypt, On-Demand TLS, Wildcard Certificates)

Automatic HTTPS is Caddy's signature feature and the primary reason many teams adopt it. Caddy automatically provisions and renews TLS certificates for every hostname it serves, using the ACME protocol to interact with certificate authorities like Let's Encrypt and ZeroSSL. This means that from the moment you start Caddy with a domain name, it will obtain a valid TLS certificate for that domain, configure HTTPS, and handle all future renewals automatically. There are no certificate files to manage, no renewal scripts to write, and no monitoring of certificate expiration dates. Caddy handles all of this transparently and reliably, making it the most operationally simple way to achieve full HTTPS coverage across your entire web infrastructure.

The ACME protocol (RFC 8555) defines a standardized way for web servers to obtain and manage TLS certificates programmatically. Caddy's ACME implementation supports all three challenge types: HTTP-01, TLS-ALPN-01, and DNS-01. The HTTP-01 challenge requires Caddy to serve a well-known token on port 80, which the certificate authority verifies by making an HTTP request. The TLS-ALPN-01 challenge uses a special TLS certificate that contains the challenge token, verified during the TLS handshake on port 443. The DNS-01 challenge requires creating a specific TXT record in the domain's DNS zone, which Caddy can do automatically if integrated with a supported DNS provider. Caddy automatically selects the best challenge type based on the server's configuration and network environment, choosing HTTP-01 for simplicity when port 80 is available, TLS-ALPN-01 when only port 443 is available, and DNS-01 when wildcard certificates are needed or when the server is behind a load balancer that cannot forward ACME challenges.

On-Demand TLS

On-demand TLS is a feature that allows Caddy to obtain TLS certificates at request time, rather than at configuration time. This is particularly powerful for SaaS platforms and hosting providers where you need to serve custom domains for customers. With on-demand TLS enabled, when a request arrives for a hostname that Caddy does not have a certificate for, Caddy will immediately obtain one if the domain is authorized and start serving HTTPS for that domain. The authorization check is performed by querying a configurable endpoint, typically your application's API, to verify that the domain is allowed. This prevents Caddy from obtaining certificates for unauthorized domains, which could be abused for phishing or other attacks.

JSON (on-demand TLS configuration)
{
    "apps": {
        "tls": {
            "automation": {
                "on_demand": {
                    "ask": "https://api.example.com/v1/caddy/ask"
                },
                "policies": [
                    {
                        "subjects": ["*.example.com"],
                        "issuers": [
                            {
                                "module": "acme"
                            }
                        ]
                    }
                ]
            }
        },
        "http": {
            "servers": {
                "srv0": {
                    "listen": [":443"],
                    "routes": [
                        {
                            "match": [{"host": ["*"]}],
                            "handle": [
                                {
                                    "handler": "reverse_proxy",
                                    "upstreams": [
                                        {"dial": "localhost:3000"}
                                    ]
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Wildcard certificates require the DNS-01 challenge type, since certificate authorities cannot verify wildcard domains via HTTP or TLS challenges. Caddy supports wildcard certificates natively and can automatically create and clean up the required DNS TXT records when integrated with DNS providers like Cloudflare, Route 53, DigitalOcean, and many others. Wildcard certificates are issued for the entire domain, for example *.example.com, allowing you to serve any subdomain without obtaining separate certificates. However, wildcard certificates do not cover the bare domain itself, so you need a separate certificate for example.com if you want to serve both the bare domain and subdomains.

Caddy's certificate management goes beyond just issuance. It also handles certificate renewal automatically, typically starting 30 days before the certificate expires. Caddy tracks certificate expiry dates and schedules renewal jobs well in advance, ensuring that certificates are always valid. If a renewal fails due to network issues or CA outages, Caddy retries with exponential backoff and logs detailed error messages. The OCSP stapling feature is also handled automatically where Caddy periodically fetches OCSP responses from the certificate authority and staples them to TLS handshakes. This improves client performance by eliminating the need for clients to check certificate revocation status separately.

When designing an automatic HTTPS system with Caddy, there are several operational considerations to keep in mind. First, ensure that your DNS records are properly configured before starting Caddy, as the ACME challenges require the domain to resolve to your server. Second, if you are behind a load balancer, ensure that port 80 or port 443 is forwarded to your Caddy instance. Third, monitor Caddy's logs for certificate issuance and renewal events, as these are critical for maintaining uptime. Fourth, consider implementing alerting on certificate expiration dates as a safety net. Fifth, test your ACME configuration in a staging environment using Let's Encrypt's staging endpoints before deploying to production to avoid hitting rate limits.

6. Reverse Proxy (Load Balancing, Health Checks, Circuit Breaking)

Caddy's reverse proxy module is one of its most feature-rich and commonly used components. It forwards requests from Caddy to one or more backend servers, acting as a gateway between clients and your application servers. The reverse proxy supports all HTTP methods, WebSocket connections, gRPC, and HTTP/2, making it suitable for virtually any backend architecture. Beyond simple proxying, it includes sophisticated load balancing, active and passive health checks, circuit breaking, request retries, and buffering capabilities that make it production-ready for high-traffic environments.

When building dynamic reverse proxy configurations that interact with Caddy's admin API, you can programmatically manage upstream backends using a C# client that translates service discovery events into Caddy configuration updates.

C# (programmatic upstream management)
public class CaddyUpstreamManager
{
    private readonly CaddyAdminClient _caddy;
    private readonly ILogger<CaddyUpstreamManager> _logger;

    public CaddyUpstreamManager(
        CaddyAdminClient caddy, ILogger<CaddyUpstreamManager> logger)
    {
        _caddy = caddy;
        _logger = logger;
    }

    public async Task SyncUpstreamsAsync(
        string routePath, List<string> healthyEndpoints)
    {
        var currentConfig = await _caddy.GetConfigAsync(
            $"apps/http/servers/srv0/routes/{routePath}");

        var existingUpstreams = currentConfig
            .GetProperty("handle")[0]
            .GetProperty("upstreams")
            .EnumerateArray()
            .Select(u => u.GetProperty("dial").GetString())
            .ToList();

        // Remove backends no longer in the healthy set
        foreach (var removed in existingUpstreams
            .Except(healthyEndpoints))
        {
            _logger.LogWarning(
                "Removing unhealthy upstream: {Upstream}", removed);
            await _caddy.RemoveUpstreamAsync(routePath, removed);
        }

        // Add newly healthy backends
        foreach (var added in healthyEndpoints
            .Except(existingUpstreams))
        {
            _logger.LogInformation(
                "Adding healthy upstream: {Upstream}", added);
            await _caddy.AddUpstreamAsync(routePath, added);
        }
    }
}

Load balancing in Caddy is configurable through the lb_policy directive in the Caddyfile or the load_balancing configuration object in JSON. Caddy supports several load balancing algorithms including random, random_choose which selects N random backends and picks the least loaded, round_robin, least_conn which routes to the backend with the fewest active connections, ip_hash which hashes the client IP to consistently route to the same backend, uri_hash which hashes the request URI, header which hashes a specific request header, and cookie which uses a cookie for session affinity. The choice of algorithm depends on your application's requirements where stateless applications benefit from round-robin or least-conn, while stateful applications may need ip_hash or cookie-based affinity.

Health checks are essential for maintaining a reliable reverse proxy. Caddy supports two types of health checks: active and passive. Active health checks periodically send requests to each backend's health endpoint and mark backends as unhealthy if they fail to respond correctly within the specified timeout. Passive health checks observe the actual traffic flowing through the proxy and mark backends as unhealthy based on error rates where if a backend starts returning too many 5xx errors or timing out, Caddy will temporarily stop routing traffic to it. Both types of health checks can be configured with custom URIs, intervals, timeouts, and status code expectations.

Caddyfile
api.example.com {
    reverse_proxy localhost:8080 localhost:8081 localhost:8082 {
        # Load balancing policy
        lb_policy least_conn

        # Active health checks
        health_uri /health
        health_interval 10s
        health_timeout 5s
        health_status 200

        # Passive health checks (circuit breaking)
        fail_duration 30s
        max_fails 5
        unhealthy_status 500 502 503
        unhealthy_interval 10s

        # Request retries on specific status codes
        retry_match {
            status 502 503 504
        }

        # Connection timeouts
        transport http {
            dial_timeout 5s
            response_header_timeout 30s
            read_timeout 60s
            write_timeout 60s
        }

        # Request headers
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_down X-Powered-By ""
    }
}

Circuit breaking in Caddy is implemented through the combination of passive health checks and the fail_duration directive. When a backend accumulates too many failures as defined by max_fails, it is marked as circuit open for the specified fail_duration. During this period, requests that would have been routed to the failed backend are instead routed to other healthy backends. After the fail duration expires, Caddy attempts to route a single request to the backend in a half-open state, and if it succeeds the backend is marked healthy again, while if it fails the circuit opens again. This pattern prevents cascading failures in distributed systems and allows backends to recover from transient issues.

The transport layer of the reverse proxy is configurable and supports both HTTP and FastCGI transports. For HTTP transport, you can configure dial timeouts, response header timeouts, read and write buffer sizes, TLS settings for backend connections, and HTTP/2 multiplexing. The transport also supports custom dial addresses, allowing you to route traffic to backends using different hostnames or IP addresses. For WebSocket and gRPC traffic, Caddy automatically detects the upgrade headers and maintains the connection for the duration of the session. When designing a reverse proxy architecture with Caddy, always configure both active and passive health checks, use fail_duration and max_fails settings for circuit breaking, configure request retries for transient errors, use header_up directives to pass client information to backends, and configure appropriate timeouts for your use case.

7. Static File Serving (File Server, Brotli Compression, Browse Directive)

Caddy's file server module provides a high-performance, secure way to serve static files from disk. It handles serving HTML, CSS, JavaScript, images, fonts, and any other static assets with proper MIME type detection, range requests for partial content, and conditional requests using ETags and Last-Modified headers. The file server is designed with security as a priority where it prevents directory traversal attacks, restricts access to hidden files by default, and integrates with Caddy's TLS system to ensure that static content is always served over HTTPS. For single-page applications, the file server supports fallback to an index file when the requested path does not correspond to a physical file, which is essential for client-side routing frameworks.

The browse directive enables automatic directory listing for any directory that does not contain an index file. This generates a clean, styled HTML page that lists the contents of the directory with file sizes, modification dates, and download links. While directory browsing is generally disabled in production for security reasons, it can be useful in development environments, documentation sites, and file sharing applications. The directory listing is customizable through templates, allowing you to change the appearance and add custom branding.

Caddyfile
static.example.com {
    root * /var/www/static
    encode gzip zstd brotli

    # Security headers for static content
    header {
        Cache-Control "public, max-age=31536000, immutable"
        X-Content-Type-Options nosniff
        Content-Security-Policy "default-src 'none'; style-src 'self'; script-src 'self'"
    }

    # SPA fallback for client-side routing
    try_files {path} /index.html

    # Serve with precompressed files
    file_server {
        precompressed gzip br zstd
    }
}

# CDN-style static asset serving
static-cdn.example.com {
    root * /var/www/cdn

    # Long cache for versioned assets
    @versioned path /assets/*
    header @versioned Cache-Control "public, max-age=31536000, immutable"

    # Short cache for non-versioned assets
    @dynamic path /images/*
    header @dynamic Cache-Control "public, max-age=3600"

    file_server
}

Compression is handled by Caddy's encode module, which can compress responses using gzip, zstd, and brotli algorithms. The encode module negotiates the best compression algorithm with the client based on the Accept-Encoding header. Brotli compression provides superior compression ratios compared to gzip, especially for text-based content. Zstd offers an excellent balance between compression speed and ratio, making it ideal for high-throughput scenarios. Caddy also supports precompressed files where if you have pre-generated .gz, .br, or .zst files alongside your original files, Caddy can serve them directly without compressing on-the-fly, which significantly reduces CPU usage for high-traffic sites.

Range requests are fully supported by Caddy's file server, which means clients can request specific byte ranges of a file. This is essential for video streaming, large file downloads, and resumable uploads. When a client sends a Range header, Caddy reads the requested byte range from the file and returns a 206 Partial Content response with the Content-Range header. This allows media players to seek to specific positions in video files and download managers to resume interrupted downloads. The file server also supports conditional requests using If-None-Match and If-Modified-Since headers, returning a 304 Not Modified response when the client's cached version is still valid. For production deployments, use precompressed files instead of on-the-fly compression, configure aggressive caching headers for versioned assets, enable try_files for SPA applications, and consider using a separate domain for static assets to enable cookie-free requests.

8. Middleware Chain (Headers, Redirects, Rewrite, Rate Limiting, Basicauth)

The middleware chain is the heart of Caddy's request processing model. Every request that enters Caddy passes through a sequence of middleware handlers, each of which can inspect, modify, or short-circuit the request. This chain-of-responsibility pattern provides a clean, composable way to add functionality to the request processing pipeline. Caddy ships with a comprehensive set of built-in middleware including headers manipulation, URL redirects, URL rewriting, basic authentication, rate limiting, request buffering, and more. Understanding how these middleware components work and how they compose is essential for designing effective Caddy configurations that are both secure and performant.

The headers middleware allows you to set, add, or delete request and response headers. This is commonly used for adding security headers like Content-Security-Policy, X-Frame-Options, and Strict-Transport-Security, removing server identification headers like Server and X-Powered-By, and setting caching headers. The headers middleware can be applied globally or to specific routes using matchers. When modifying response headers, the middleware runs after the terminal handler, allowing it to add or modify headers in the response before it is sent to the client.

The redirect middleware provides a simple way to issue HTTP redirects (301, 302, 307, 308) based on request properties. This is commonly used for redirecting HTTP to HTTPS, redirecting non-www to www or vice versa, redirecting old URLs to new locations, and implementing custom redirect rules. The redirect middleware supports status code configuration, URL templating using Caddy placeholders like {http.request.host} and {http.request.uri}, and conditional matching.

Caddyfile
example.com {
    # Redirect HTTP to HTTPS
    @http protocol http
    redir @http https://{host}{uri} permanent

    # Redirect non-www to www
    @nonwww host example.com
    redir @nonwww https://www.example.com{uri} permanent

    # Rewrite API paths
    @api path /api/v1/* /api/v2/*
    rewrite @api /api{uri}

    # Basic authentication with bcrypt passwords
    basicauth * {
        admin $2a$14$RZnMGOBzNfPCHMXrHxuKZOeQIqFhJSYqOvz8BxQ3y5A7v
        user1 $2a$14$kR3wN5q8vXy2mL9pF7dZeOcQHt6Bn4J1iS8eW2aR5gD9
    }

    # Rate limiting with zone definition
    rate_limit {
        zone api_zone {
            key {remote_host}
            events 100
            window 1m
        }
    }

    reverse_proxy localhost:8080
}

The rewrite middleware modifies the request URI internally without issuing a redirect to the client. This is essential for routing requests to different backend handlers based on the request path. For example, in a microservices architecture, you might rewrite /api/v1/users/* to /users/* before passing the request to the user service. Rewrites are invisible to the client, and the browser's address bar does not change. This differs from redirects which instruct the client to make a new request to a different URI.

Basic authentication is implemented by Caddy's basicauth middleware, which validates HTTP Basic credentials against a list of usernames and hashed passwords. The passwords must be bcrypt-hashed using the $2a$ prefix, which provides strong protection against brute force attacks. The basicauth middleware can be applied to specific routes using matchers, allowing you to protect certain endpoints while leaving others public. Rate limiting is a critical middleware for protecting your application from abuse, DDoS attacks, and excessive resource consumption. Community plugins like caddy-ratelimit implement token bucket or sliding window rate limiting algorithms.

When designing middleware chains, there are several best practices to follow. First, place security-related middleware like headers, authentication, and rate limiting early in the chain so that unauthorized requests are rejected before consuming backend resources. Second, place rewrite middleware before the terminal handler but after authentication, so that rewrites do not bypass security checks. Third, place encoding middleware last to ensure it operates on the final response. Fourth, use named matchers to apply middleware selectively rather than globally, which improves performance and reduces unintended side effects. Fifth, test your middleware chain by enabling debug logging and examining the request processing flow for different request patterns.

9. TLS Configuration (OCSP Stapling, Client Auth, Session Tickets)

Caddy's TLS configuration provides fine-grained control over the TLS behavior of your server, including protocol versions, cipher suites, OCSP stapling, client certificate authentication, session tickets, and certificate chain management. While Caddy's automatic HTTPS handles most TLS concerns automatically, understanding the TLS configuration options is essential for security-critical deployments that need to comply with specific security policies, meet regulatory requirements, or support legacy clients. Caddy's TLS module is built on Go's standard crypto/tls package with significant enhancements for certificate management, OCSP handling, and performance optimization.

OCSP stapling is a TLS extension that allows the server to include the certificate's revocation status directly in the TLS handshake, rather than requiring the client to check with the certificate authority separately. This improves both security and performance where clients get the revocation status immediately without making an additional network request, and the certificate authority's OCSP responder receives less traffic. Caddy automatically staples OCSP responses to certificates, fetching and refreshing them before they expire.

JSON (advanced TLS configuration)
{
    "apps": {
        "tls": {
            "automation": {
                "policies": [
                    {
                        "subjects": ["example.com", "*.example.com"],
                        "issuers": [
                            {
                                "module": "acme",
                                "challenges": {
                                    "dns": {
                                        "provider": {
                                            "name": "cloudflare",
                                            "api_token": "{env.CF_API_TOKEN}"
                                        }
                                    }
                                }
                            }
                        ],
                        "key_type": "ec256"
                    }
                ],
                "ocsp_stapling": {
                    "resolvers": ["1.1.1.1:53", "8.8.8.8:53"]
                }
            },
            "certificates": {
                "load_files": [
                    {
                        "certificate": "/etc/ssl/custom.crt",
                        "key": "/etc/ssl/custom.key",
                        "tags": ["custom"]
                    }
                ]
            }
        },
        "http": {
            "servers": {
                "secure": {
                    "listen": [":443"],
                    "tls": {
                        "protocols": ["tls1.2", "tls1.3"],
                        "cipher_suites": [
                            "TLS_AES_256_GCM_SHA384",
                            "TLS_CHACHA20_POLY1305_SHA256",
                            "TLS_AES_128_GCM_SHA256"
                        ],
                        "client_auth": {
                            "mode": "require_and_verify",
                            "trusted_ca_certs_file": "/etc/ssl/ca.crt"
                        }
                    }
                }
            }
        }
    }
}

Client certificate authentication (mTLS) allows the server to verify the identity of clients using X.509 certificates. This is commonly used in microservices architectures, API security, and zero-trust environments. Caddy supports several mTLS modes: none (no client certificate required), request (request a certificate but do not require it), require_if_given (require a certificate only if one is presented), and require_and_verify (require and validate a certificate against a CA). When client authentication is enabled, Caddy verifies the client certificate against a configurable set of trusted CA certificates and can extract client identity information for use in request routing and authorization decisions.

Session tickets are a TLS extension that allows session resumption without the full TLS handshake, significantly reducing latency for returning clients. When a client connects for the first time, the server generates an encrypted session ticket containing the session state and sends it to the client. On subsequent connections, the client presents the session ticket and the server decrypts it to restore the previous session state, skipping the key exchange. Caddy supports TLS 1.3 session tickets by default and also supports TLS 1.2 session resumption via session IDs. The session ticket keys are rotated periodically with Caddy generating new keys every 24 hours by default.

When configuring TLS for production, always use TLS 1.2 or later, use ECDSA certificates instead of RSA for better performance, enable OCSP stapling, configure session tickets for session resumption, monitor your TLS configuration using tools like SSL Labs, and consider enabling 0-RTT early data for TLS 1.3 if your application can handle replay attacks safely.

10. DNS Providers (Cloudflare, Route53, DigitalOcean, Custom)

DNS provider integration is essential for Caddy's automatic HTTPS when you need wildcard certificates that require DNS-01 challenges or when your server is behind a load balancer or firewall that prevents HTTP-01 and TLS-ALPN-01 challenges. Caddy supports a growing ecosystem of DNS providers through its libdns and caddy-dns modules, allowing it to automatically create and clean up DNS TXT records for ACME DNS-01 challenges. This integration means that Caddy can obtain wildcard certificates without any manual DNS configuration, making it possible to serve *.example.com with full automatic HTTPS.

Cloudflare is one of the most popular DNS providers for use with Caddy, and the caddy-dns/cloudflare module provides seamless integration. The module uses Cloudflare's API to create and delete DNS TXT records for ACME challenges. To use it, you need a Cloudflare API token with the DNS:Edit permission for your zone. The token can be provided in the Caddy configuration or as an environment variable. Once configured, Caddy will automatically create the _acme-challenge.example.com TXT record, wait for DNS propagation, complete the ACME challenge, and then clean up the TXT record.

Caddyfile
{
    acme_dns cloudflare {env.CF_API_TOKEN}
}

# Cloudflare DNS provider for wildcard certificates
*.example.com, example.com {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
    reverse_proxy localhost:8080
}

# AWS Route53 provider
*.app.example.com, app.example.com {
    tls {
        dns route53 {
            regions us-east-1
            credentials {
                access_key_id {env.AWS_ACCESS_KEY_ID}
                secret_access_key {env.AWS_SECRET_ACCESS_KEY}
            }
        }
    }
    reverse_proxy localhost:8081
}

# DigitalOcean provider
*.do.example.com, do.example.com {
    tls {
        dns digitalocean {env.DO_API_TOKEN}
    }
    reverse_proxy localhost:8082
}

# RFC 2136 Dynamic DNS - universal fallback
*.custom.example.com, custom.example.com {
    tls {
        dns rfc2136 {
            nameserver 192.168.1.1:53
            key_name caddy-key
            key_alg hmac-sha256
            key_secret {env.TSIG_SECRET}
        }
    }
    reverse_proxy localhost:8083
}

AWS Route 53 integration enables Caddy to use Amazon's DNS service for ACME challenges. The Route 53 module uses AWS IAM credentials to create and delete TXT records via the Route 53 API. The module supports all Route 53 regions and handles the asynchronous nature of Route 53 changes by polling for completion before proceeding with the ACME challenge. For production deployments on AWS, using an IAM role attached to the EC2 instance or EKS pod is recommended over hardcoding access keys.

When configuring DNS providers for Caddy, ensure that API credentials have minimum permissions necessary, monitor your DNS provider's API rate limits, consider using the RFC 2136 module as a universal fallback for unsupported providers, and test DNS propagation behavior in your network environment. For environments where DNS provider integration is not possible, Caddy's HTTP-01 and TLS-ALPN-01 challenges provide alternatives, though they cannot issue wildcard certificates.

11. API and Remote Control (Admin API, Runtime Configuration Changes)

Caddy's admin API is a built-in HTTP server that provides programmatic access to Caddy's configuration and runtime state. By default, it listens on localhost:2019 and provides RESTful endpoints for loading, updating, inspecting, and removing configurations. The admin API is not just a convenience feature; it is the primary mechanism for managing Caddy in dynamic environments where configurations change frequently. Unlike traditional web servers that require file edits and process restarts, Caddy's admin API allows you to make configuration changes atomically and without any downtime.

The primary endpoint for configuration management is POST /load, which accepts a complete JSON configuration and replaces the running configuration atomically. When Caddy receives a new configuration, it first validates the entire configuration against the schemas of all loaded modules. If validation passes, Caddy prepares the new configuration internally, creating new listener pools, establishing backend connections, provisioning TLS certificates, and initializing new modules. Only when all preparations are complete does Caddy atomically switch to the new configuration.

C# (Admin API management client)
public class CaddyAdminClient
{
    private readonly HttpClient _http;
    private readonly string _baseUrl;

    public CaddyAdminClient(string baseUrl = "http://localhost:2019")
    {
        _baseUrl = baseUrl;
        _http = new HttpClient { BaseAddress = new Uri(baseUrl) };
    }

    public async Task<bool> LoadConfigAsync(string jsonConfig)
    {
        var content = new StringContent(jsonConfig,
            Encoding.UTF8, "application/json");
        var response = await _http.PostAsync("/load", content);
        return response.IsSuccessStatusCode;
    }

    public async Task<JsonElement> GetConfigAsync(string path = "/")
    {
        var response = await _http.GetAsync($"/config/{path}");
        var json = await response.Content.ReadAsStringAsync();
        return JsonSerializer.Deserialize<JsonElement>(json);
    }

    public async Task<bool> AddRouteAsync(
        string serverName, JsonElement routeConfig)
    {
        var path = $"config/apps/http/servers/{serverName}/routes";
        var content = new StringContent(
            routeConfig.GetRawText(),
            Encoding.UTF8, "application/json");
        var response = await _http.PostAsync($"/config/{path}", content);
        return response.IsSuccessStatusCode;
    }

    public async Task<bool> RemoveRouteAsync(
        string serverName, int routeIndex)
    {
        var path = $"config/apps/http/servers/{serverName}/routes/{routeIndex}";
        var response = await _http.DeleteAsync($"/config/{path}");
        return response.IsSuccessStatusCode;
    }

    public async Task GracefulStopAsync()
    {
        await _http.PostAsync("/stop", null);
    }
}

The incremental configuration API is where Caddy's admin API truly shines. Instead of replacing the entire configuration with POST /load, you can use POST /config/{path} to modify specific parts of the configuration. The path parameter follows a hierarchical structure that mirrors the JSON configuration tree. This allows you to add new routes, update existing handlers, modify TLS settings, and change logging configuration without touching the rest of the configuration. The path-based API supports POST for create or append, PUT for replace, and DELETE for remove operations.

Security is critical when exposing Caddy's admin API. By default, the API only listens on localhost. For remote access, enable TLS on the admin API and configure authentication. In production, never expose the admin API directly to the internet without proper authentication and encryption. A common pattern is to use a VPN or private network for API access, with the admin API bound to a private IP address. When designing systems that interact with Caddy's admin API, implement idempotent operations, store configuration snapshots for rollback capability, use the incremental API for frequent small changes, implement health checks after each change, and monitor Caddy's logs for configuration change events to maintain an audit trail.

12. Logging (Access Logs, Log Levels, Custom Formatters)

Caddy's logging system provides comprehensive observability into request processing, error conditions, and operational events. The logging module supports multiple output destinations including stdout, stderr, files, and custom writers, multiple log formats including JSON, console, and custom formatters, and fine-grained filtering based on log level, module, and request properties. Proper logging is essential for debugging issues, monitoring performance, detecting security threats, and maintaining compliance with operational requirements. Caddy's logging system is designed to be both powerful and performant, with asynchronous log writing, log rotation, and structured logging that integrates well with modern observability stacks like the ELK stack, Grafana, and Datadog.

Access logs record details about each HTTP request processed by Caddy, including the client's IP address, the requested URI, the HTTP method, the response status code, the response size, the processing duration, and any custom fields you choose to include. Caddy's access logs are structured by default, outputting each log entry as a JSON object with clearly named fields. This structured format makes it easy to parse, filter, and analyze logs using tools like jq, Elasticsearch, or Splunk.

Caddyfile
{
    log {
        output file /var/log/caddy/access.log {
            roll_size 100MiB
            roll_keep 10
            roll_keep_for 720h
        }
        format json
        level INFO
    }
}

example.com {
    # Per-site access log
    log {
        output file /var/log/caddy/example.log {
            roll_size 50MiB
            roll_keep 5
        }
        format json
    }

    # Debug logging for reverse proxy module only
    log {
        output stdout
        format console
        level DEBUG
        module http.handlers.reverse_proxy
    }

    reverse_proxy localhost:8080
}

You can build custom log processors in C# that consume Caddy structured JSON logs and generate real-time dashboards.

C# (Caddy log processor)
public class CaddyLogProcessor
{
    private readonly Channel<CaddyAccessLog> _logChannel;
    private readonly IMetricsCollector _metrics;

    public CaddyLogProcessor(IMetricsCollector metrics)
    {
        _metrics = metrics;
        _logChannel = Channel.CreateBounded<CaddyAccessLog>(
            new BoundedChannelOptions(10000));
    }

    public async Task ProcessLogEntryAsync(string jsonLine)
    {
        var entry = JsonSerializer.Deserialize<CaddyAccessLog>(
            jsonLine, new JsonSerializerOptions
            {
                PropertyNameCaseInsensitive = true
            });

        if (entry == null) return;

        _metrics.RecordRequestDuration(
            entry.Request?.Uri ?? "unknown",
            entry.Request?.Method ?? "unknown",
            entry.StatusCode,
            entry.Duration);

        if (entry.StatusCode >= 500)
        {
            _metrics.IncrementErrorCount(
                entry.Request?.Host ?? "unknown",
                entry.StatusCode);
        }
    }
}

public class CaddyAccessLog
{
    public string Level { get; set; }
    public int StatusCode { get; set; }
    public TimeSpan Duration { get; set; }
    public RequestLog Request { get; set; }
}

Caddy supports six log levels: DEBUG, INFO, WARN, ERROR, DPANIC, and FATAL. Each level captures progressively more severe events. DEBUG level provides detailed information about request processing including matcher evaluation and handler execution. INFO level captures normal operational events like server startup and certificate issuance. WARN level captures non-critical issues like deprecated configurations. ERROR level captures failures that affect request processing. DPANIC and FATAL capture critical system-level failures. In production, INFO is typically the recommended level while DEBUG can be enabled temporarily for specific modules when troubleshooting.

Log rotation is handled automatically by Caddy when outputting to files. The roll_size option specifies the maximum file size before rotation, roll_keep specifies how many rotated files to keep, and roll_keep_for specifies how long to keep rotated files. This built-in rotation eliminates the need for external tools like logrotate and ensures that log files do not grow unbounded. Custom formatters use Go's text/template syntax with access to all of Caddy's logging fields, allowing you to create Apache Combined format for compatibility with existing tools or simplified debugging outputs.

When designing logging for production Caddy deployments, configure separate log files for different sites and modules to simplify debugging, use JSON format for machine parsing and log aggregation, set appropriate log levels for each module, implement log shipping to a centralized logging service before rotation, and monitor for error-level entries that indicate operational issues requiring attention.

13. Performance (HTTP/2, HTTP/3 QUIC, Connection Pooling)

Caddy is designed for high performance and can handle thousands of concurrent connections with low latency and efficient resource usage. It supports HTTP/1.1, HTTP/2, and HTTP/3 QUIC protocols, providing optimal performance for modern browsers and clients. HTTP/2 enables multiplexed streams over a single TCP connection, header compression using HPACK, and server push. HTTP/3, built on the QUIC protocol, eliminates head-of-line blocking at the transport layer, provides 0-RTT connection establishment, and uses UDP instead of TCP for improved performance on unreliable networks. Caddy's Go-based architecture provides excellent concurrency through goroutines, allowing it to efficiently handle large numbers of simultaneous connections without the process-per-connection or thread-pool models used by traditional web servers.

HTTP/2 support in Caddy is enabled by default for all HTTPS connections. When a client connects over TLS, Caddy automatically negotiates HTTP/2 using ALPN during the TLS handshake. HTTP/2 provides several performance benefits: multiplexing allows multiple requests and responses to be in flight simultaneously, header compression using HPACK reduces the size of repeated headers, and server push allows the server to proactively send resources. Caddy also supports HTTP/1.1 fallback for clients that do not support HTTP/2.

HTTP/3 and QUIC support in Caddy provides the next generation of web performance. QUIC is a UDP-based transport protocol that eliminates head-of-line blocking, provides built-in TLS 1.3 encryption, supports connection migration for seamless network transitions, and enables 0-RTT resumption for repeat connections. Caddy's HTTP/3 implementation shares certificate caches and OCSP responses between HTTP/2 and HTTP/3 connections. When HTTP/3 is enabled, Caddy advertises it to clients using the Alt-Svc header.

JSON (HTTP/3 and performance configuration)
{
    "apps": {
        "http": {
            "servers": {
                "high-perf": {
                    "listen": [":443", ":8443"],
                    "protocols": ["h1", "h2", "h3"],
                    "routes": [
                        {
                            "match": [{"host": ["example.com"]}],
                            "handle": [
                                {
                                    "handler": "reverse_proxy",
                                    "upstreams": [
                                        {"dial": "localhost:8080"},
                                        {"dial": "localhost:8081"}
                                    ],
                                    "transport": {
                                        "protocol": "http",
                                        "read_buffer": 16384,
                                        "write_buffer": 16384,
                                        "dial_timeout": "5s"
                                    },
                                    "load_balancing": {
                                        "selection_policy": {
                                            "policy": "least_conn"
                                        }
                                    },
                                    "flush_interval": -1
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

Connection pooling is a critical performance optimization for reverse proxy deployments. When Caddy proxies requests to backend servers, it maintains a pool of persistent connections to each backend, avoiding the overhead of establishing new connections for every request. The pool size and behavior are configurable through the transport settings. For high-traffic deployments, increasing the maximum idle connections per host can reduce latency and improve throughput.

You can build a C# client that leverages Caddy HTTP/3 support to optimize connections from .NET applications.

C# (HTTP/3 optimized client for Caddy)
public class CaddyHttp3Client : IDisposable
{
    private readonly SocketsHttpHandler _handler;
    private readonly HttpClient _client;

    public CaddyHttp3Client(string caddyBaseUrl)
    {
        _handler = new SocketsHttpHandler
        {
            EnableMultipleHttp2Connections = true,
            ConnectCallback = async (context, cancellationToken) =>
            {
                var socket = new Socket(
                    AddressFamily.InterNetwork,
                    SocketType.Stream,
                    ProtocolType.Tcp);
                await socket.ConnectAsync(
                    context.DnsEndPoint, cancellationToken);
                return new NetworkStream(socket, ownsSocket: true);
            }
        };

        _client = new HttpClient(_handler)
        {
            BaseAddress = new Uri(caddyBaseUrl)
        };
    }

    public async Task<HttpResponseMessage> SendOptimizedAsync(
        HttpRequestMessage request,
        CancellationToken ct = default)
    {
        // Set Alt-Svc header awareness for HTTP/3 upgrade
        request.Version = HttpVersion.Version30;
        request.VersionPolicy = HttpVersionPolicy.RequestVersionExact;
        return await _client.SendAsync(request, ct);
    }

    public void Dispose()
    {
        _client?.Dispose();
        _handler?.Dispose();
    }
}

When optimizing Caddy for performance, enable HTTP/3 QUIC for the best client performance, configure appropriate buffer sizes for the reverse proxy transport, enable response flushing for streaming endpoints, use the least_conn load balancing policy for backends with variable response times, configure appropriate timeouts, enable precompressed file serving, use ECDSA certificates instead of RSA for faster TLS handshakes, and monitor Caddy's performance using Prometheus metrics through the caddy-prometheus plugin to identify bottlenecks and optimization opportunities.

14. Modules and Plugins (Custom Middleware, Third-Party Plugins)

Caddy's module system is the foundation of its extensibility. Every feature in Caddy, from the HTTP server to TLS management to logging, is implemented as a module. Modules are Go packages that implement specific interfaces defined by Caddy's framework, and they are loaded at runtime based on the configuration. This modular architecture means that Caddy's core binary can be extended with new functionality without modifying the source code. The module system supports hot-loading through the admin API, allowing new modules to be registered and configured at runtime.

Caddy modules are categorized into several types: Handler modules process HTTP requests like the reverse proxy and file server. Matcher modules evaluate request properties for routing decisions. Issuer modules obtain TLS certificates like the ACME issuer. Storage modules provide persistence for certificates and configuration. App modules provide top-level functionality. Each module type has a specific interface that must be implemented, and Caddy validates that modules conform to these interfaces at load time.

C# (conceptual custom middleware pattern)
// Pattern for building a custom Caddy-style middleware handler
public class RequestIdMiddleware
{
    private readonly RequestDelegate _next;
    private readonly string _headerName;

    public RequestIdMiddleware(
        RequestDelegate next, string headerName = "X-Request-ID")
    {
        _next = next;
        _headerName = headerName;
    }

    public async Task InvokeAsync(HttpContext context)
    {
        // Generate unique request ID if not present
        var requestId = context.Request.Headers[_headerName].FirstOrDefault()
            ?? Guid.NewGuid().ToString("N");

        // Add to request headers for upstream
        context.Request.Headers[_headerName] = requestId;

        // Process the rest of the pipeline
        await _next(context);

        // Add to response headers for client
        context.Response.Headers[_headerName] = requestId;
    }
}

// Configuration model for the middleware
public class RequestIdOptions
{
    public string HeaderName { get; set; } = "X-Request-ID";
    public bool GenerateIfMissing { get; set; } = true;
    public int Length { get; set; } = 32;
}

// Registration pattern (similar to Caddy module registration)
public static class RequestIdModule
{
    public const string ModuleName = "http.handlers.request_id";

    public static void Register()
    {
        // Register module with Caddy's module registry
        // Equivalent to caddy.RegisterModule() in Go
    }
}

Building a custom module in Caddy involves implementing the appropriate Go interface and registering the module with Caddy's module registry. For example, to build a custom HTTP handler, you would implement the caddyhttp.MiddlewareHandler interface, which requires a ServeHTTP method. The module also needs to implement the caddy.Provisioner interface for initialization and the caddy.Validator interface for configuration validation. Once implemented, the module is registered using the init() function and the caddy.RegisterModule() call.

The community has developed a rich ecosystem of third-party plugins for Caddy. Notable plugins include caddy-security providing authentication, authorization, and security features like OAuth2, OpenID Connect, and RBAC, caddy-ratelimit providing rate limiting with token bucket and sliding window algorithms, and caddy-prometheus exposing Prometheus metrics for monitoring. These plugins can be integrated into custom Caddy builds using xcaddy, Caddy's official build tool that compiles a custom binary with the specified plugins. This gives you a single binary with exactly the features you need.

15. Security Features (Security Headers, CSP, HSTS)

Security is a first-class concern in Caddy's design, and it provides numerous features for building secure web infrastructure. Caddy's security approach goes beyond just automatic HTTPS to include comprehensive security header management, Content Security Policy (CSP) support, HTTP Strict Transport Security (HSTS), protection against common web attacks, and secure defaults that minimize the attack surface. Unlike traditional web servers where security features require manual configuration, Caddy encourages secure configurations through its simple syntax and sensible defaults.

Security headers are HTTP response headers that instruct browsers on how to handle content, providing defense-in-depth against various attack vectors. Caddy's headers middleware makes it straightforward to add comprehensive security headers to all responses. The most critical security headers include Content-Security-Policy which controls which resources the browser can load, Strict-Transport-Security which forces HTTPS, X-Content-Type-Options which prevents MIME sniffing, X-Frame-Options which prevents clickjacking, Referrer-Policy which controls referrer information, and Permissions-Policy which controls browser feature access.

Caddyfile
example.com {
    header {
        # HSTS: Force HTTPS for 1 year
        Strict-Transport-Security "max-age=31536000; includeSubDomains; preload"

        # Prevent MIME sniffing
        X-Content-Type-Options nosniff

        # Prevent clickjacking
        X-Frame-Options DENY

        # Control referrer information
        Referrer-Policy strict-origin-when-cross-origin

        # Control browser features
        Permissions-Policy "camera=(), microphone=(), geolocation=(self), payment=()"

        # Remove server identification
        -Server
        -X-Powered-By

        # Content Security Policy
        Content-Security-Policy "default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.example.com; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; font-src 'self' https://fonts.gstatic.com; connect-src 'self' https://api.example.com; frame-ancestors 'none'; base-uri 'self'; form-action 'self'"

        # Cross-Origin policies
        Cross-Origin-Opener-Policy same-origin
        Cross-Origin-Resource-Policy same-origin
        Cross-Origin-Embedder-Policy require-corp
    }

    reverse_proxy localhost:8080
}

Content Security Policy (CSP) is one of the most powerful security headers but also the most complex to configure correctly. CSP allows you to whitelist specific sources for scripts, styles, images, fonts, and other resources, preventing the browser from loading resources from unauthorized sources. This is particularly effective against cross-site scripting (XSS) attacks. A well-configured CSP ensures that even if an attacker manages to inject a script tag, the browser will refuse to execute it because the source is not in the whitelist. However, CSP requires careful configuration to avoid breaking legitimate functionality, so test in report-only mode using Content-Security-Policy-Report-Only before enforcing.

HSTS (HTTP Strict Transport Security) tells browsers to only connect using HTTPS. When a browser receives the HSTS header, it remembers the policy for the specified max-age duration and automatically upgrades all HTTP requests to HTTPS. The includeSubDomains directive extends the policy to all subdomains, and the preload directive allows your domain to be included in browsers' built-in HSTS preload lists. Since Caddy automatically handles HTTP-to-HTTPS redirects and certificate management, enabling HSTS is a natural extension that provides additional protection against protocol downgrade attacks.

When implementing security headers with Caddy, follow a defense-in-depth approach. Start with the most critical headers that have minimal risk of breaking functionality, then progressively add more restrictive headers like CSP and Permissions-Policy. Use CSP report-only mode to identify violations, regularly review and update security headers, and use automated security scanning tools like Mozilla Observatory to verify your configuration meets current standards.

16. Comparison with Nginx, Apache, Traefik, Envoy

Understanding how Caddy compares to other popular web servers and proxies is essential for making informed architectural decisions. Each web server has its own strengths, weaknesses, and design philosophies, and the best choice depends on your specific requirements, team expertise, and operational context. Caddy's unique value proposition is its combination of automatic HTTPS, simple configuration, dynamic configuration API, and modern protocol support. However, it may not be the best choice for every scenario, and understanding the tradeoffs is critical for senior engineers making infrastructure decisions.

Caddy vs Nginx

Nginx is the most widely used web server in the world, powering approximately 34% of all websites. Its primary strengths are raw performance especially for static file serving and concurrent connections, a massive ecosystem of modules and configurations, and battle-tested reliability in the most demanding production environments. However, Nginx requires manual TLS certificate management typically using certbot, has a more complex configuration syntax, and does not support dynamic configuration without reloading. Caddy provides a significantly simpler experience with automatic HTTPS, a more readable configuration format, and a full REST API for runtime changes. For teams that prioritize developer experience and operational simplicity, Caddy is the better choice. For teams that need maximum performance for high-traffic static file serving or have extensive existing Nginx configurations, continuing with Nginx may be more practical.

Caddy vs Traefik

Traefik is Caddy's closest competitor in terms of design philosophy where both are modern, Go-based servers with automatic HTTPS and dynamic configuration. However, they have different primary use cases. Traefik was designed from the ground up for containerized and microservices environments, with native integration with Docker, Kubernetes, Consul, and other service discovery mechanisms. It automatically detects new containers and configures routing without manual intervention, making it ideal for dynamic environments where services are frequently created and destroyed. Caddy, on the other hand, is designed as a general-purpose web server with a more flexible configuration model that works well in both containerized and traditional environments. Choose Traefik if you are running a Kubernetes cluster with thousands of microservices that change frequently. Choose Caddy if you need a flexible, programmable web server that works across different deployment environments with a more predictable configuration model.

Caddy vs Envoy

Envoy is a high-performance L4/L7 proxy originally developed at Lyft and now the data plane for the Istio service mesh. Envoy is designed for advanced networking scenarios including service mesh, observability, and fine-grained traffic management. It provides sophisticated features like circuit breaking, rate limiting, retry policies, outlier detection, and distributed tracing through a rich xDS API. However, Envoy has significantly higher operational complexity where its configuration is YAML-based and verbose, and it typically requires a control plane like Istio for management. Caddy provides a much simpler experience for common web server use cases while still offering advanced features. For most web server and reverse proxy use cases, Caddy provides the right balance of features and simplicity. Envoy is the better choice when you need advanced L4/L7 proxying capabilities, service mesh integration, or fine-grained observability in a microservices architecture.

17. Interview Q&A

The following questions and answers are designed for senior+ engineering interviews, covering Caddy's architecture, configuration, automatic HTTPS, performance, and operational aspects. Each answer provides depth beyond the basics, demonstrating the kind of understanding expected at the senior and staff engineering levels.

Q1: How does Caddy's automatic HTTPS work, and what happens when a certificate renewal fails?

Answer: Caddy's automatic HTTPS uses the ACME protocol to obtain TLS certificates from Let's Encrypt or ZeroSSL. When Caddy starts with a domain configured, it generates a key pair, creates an ACME order, completes the required challenge (HTTP-01, TLS-ALPN-01, or DNS-01), and receives the certificate. Caddy stores the certificate and sets up automatic renewal starting 30 days before expiry. When a renewal fails, Caddy retries with exponential backoff, typically retrying after 5 minutes, then 15 minutes, then 1 hour, and so on. If renewal fails persistently, Caddy continues serving with the existing certificate until it either succeeds in renewing or the certificate expires. Caddy logs all renewal attempts and failures, making it easy to monitor and alert on renewal issues. In practice, renewal failures are rare because Let's Encrypt has very high availability and Caddy's retry mechanism handles most transient failures. However, it is important to monitor certificate expiry dates as a safety net.

Q2: Explain Caddy's directive order and why it matters for request processing.

Answer: Caddy processes directives in a predefined order that determines the execution sequence of middleware. The order is designed to ensure correct behavior where root is processed first to set the file root, header is processed early to set response headers, redir is processed before rewrite to ensure redirects happen before internal rewrites, and reverse_proxy is processed after security middleware to ensure authenticated requests reach the backend. The complete order includes: bind, root, header, redir, encode, tls, basicauth, forward_auth, request_body, respond, reverse_proxy, file_server, and others. This order matters because middleware that runs earlier can short-circuit the chain. For example, if the basicauth middleware rejects a request, the reverse proxy never receives it. Understanding this order is critical for debugging unexpected behavior.

Q3: How would you design a multi-tenant SaaS platform using Caddy's on-demand TLS?

Answer: On-demand TLS is ideal for multi-tenant SaaS platforms where each customer has a custom domain. The design would use a wildcard certificate for your platform domain and on-demand TLS for customer custom domains. When a request arrives for a custom domain, Caddy queries an authorization endpoint to verify that the domain is registered to a customer. If authorized, Caddy obtains a TLS certificate on-the-fly using DNS-01 challenges. The authorization endpoint should be fast and cached. The backend routing would use Caddy's JSON API to dynamically add and remove routes as customers onboard and offboard. Critical design considerations include rate limiting ACME challenge requests, caching authorization results, monitoring certificate inventory, and implementing graceful fallback for certificate issuance failures.

Q4: Compare Caddy's Caddyfile and JSON configuration formats. When would you use each?

Answer: The Caddyfile is a simplified, human-readable format designed for common use cases, covering about 80-90% of configuration needs and compiling down to JSON internally. Use it when writing static configurations, managing a small number of sites, or when readability and simplicity are priorities. The JSON format is Caddy's complete configuration representation providing full access to every option and is the format used by the admin API. Use it when you need dynamic configuration via API, features not expressible in the Caddyfile, programmatic configuration generation, or fine-grained control over Caddy's internal modules. Most teams start with the Caddyfile and migrate to JSON as requirements grow more complex.

Q5: How does Caddy handle connection management and what are the performance implications?

Answer: Caddy manages connections through Go's net package with connection pooling for reverse proxy upstreams. For incoming connections, Caddy uses Go's standard HTTP server with configurable timeouts for read, write, and idle connections. The connection pool for reverse proxy maintains persistent connections to backends, reducing connection setup overhead for repeated requests. HTTP/2 multiplexing allows multiple requests over a single TCP connection, reducing the number of connections needed. HTTP/3 QUIC provides even better connection efficiency with 0-RTT resumption. Performance implications include memory usage per connection (Go goroutines are lightweight at ~2KB each), connection reuse benefits, and the overhead of TLS handshakes for new connections. For high-traffic deployments, tuning the maximum idle connections per host, connection timeouts, and buffer sizes can significantly impact performance.

Q6: What are the trade-offs of using Caddy's on-demand TLS in a production environment?

Answer: On-demand TLS provides incredible flexibility for multi-tenant platforms but introduces several trade-offs. The primary benefit is that you can serve any customer domain without pre-provisioning certificates, making onboarding instant. However, the first request for a new domain incurs the latency of ACME certificate issuance, which can take 10-60 seconds. This cold-start latency can be mitigated with pre-warming by triggering certificate issuance when a customer adds their domain, rather than waiting for the first request. Security considerations include the need for a robust authorization endpoint to prevent unauthorized certificate issuance, rate limiting to prevent abuse of the ACME protocol, and monitoring for unusual certificate issuance patterns. Operational considerations include tracking certificate inventory across hundreds or thousands of domains, handling certificate renewal at scale, and ensuring that the DNS provider API can handle the volume of DNS-01 challenges. Cost considerations include the rate limits imposed by Let's Encrypt (50 certificates per registered domain per week) and the potential need for multiple ACME accounts to work around these limits.

Q7: How would you implement blue-green deployment using Caddy?

Answer: Blue-green deployment with Caddy leverages its dynamic configuration API to switch traffic between two identical environments without downtime. The process starts with both blue and green backends running and registered as upstreams in Caddy's reverse proxy. Initially, all traffic goes to the blue environment. When deploying a new version, you start the green environment and configure health checks to verify it is ready. Once healthy, you use Caddy's admin API to update the reverse proxy upstreams to point to the green environment. Caddy atomically switches traffic with no dropped connections. The old blue environment remains running and can receive a portion of traffic for validation. If issues are detected, you can instantly roll back by updating the upstreams to point back to blue. This approach is implemented by maintaining a configuration template where only the upstream addresses change between deployments, and using a deployment script that reads the current configuration, modifies the upstreams, and pushes the updated configuration via the admin API.

Q8: Explain how Caddy's module system enables extensibility and how you would build a custom authentication module.

Answer: Caddy's module system provides extensibility through Go interfaces that define contracts for different module types. An HTTP handler module must implement the caddyhttp.MiddlewareHandler interface with a ServeHTTP method. A custom authentication module would implement this interface along with the caddy.Provisioner interface for initialization and caddy.Validator for configuration validation. The module would intercept requests, check for authentication tokens or credentials, and either pass the request to the next handler or return a 401 response. Configuration would be defined using Caddy's config module system with struct tags for JSON serialization. The module is registered in an init() function using caddy.RegisterModule() and integrated into Caddy builds using xcaddy. In production, the module would need to handle concurrent requests efficiently, support caching of authentication results to reduce latency, and integrate with Caddy's logging system for audit trails.

Q9: How do you monitor and troubleshoot Caddy in a production environment?

Answer: Monitoring Caddy in production involves several complementary approaches. First, configure structured JSON logging with appropriate log levels, shipping logs to a centralized logging platform like ELK or Datadog for analysis and alerting. Second, use the caddy-prometheus plugin to expose metrics including request counts, response times, error rates, active connections, TLS certificate expiry, and upstream health status. Third, set up alerting on key metrics like 5xx error rates, response latency percentiles, certificate expiry dates, and upstream health check failures. Fourth, use Caddy's admin API to inspect the running configuration and verify that all routes, handlers, and TLS certificates are configured correctly. Fifth, enable debug logging for specific modules when troubleshooting issues, which provides detailed information about request processing, matcher evaluation, and upstream communication. Common troubleshooting scenarios include debugging certificate issuance failures by checking ACME challenge logs, investigating slow responses by analyzing upstream latency metrics, and diagnosing routing issues by examining matcher evaluation in debug logs.

Q10: What are the security implications of exposing Caddy's admin API, and how would you secure it?

Answer: Exposing Caddy's admin API without proper security creates a critical vulnerability because an attacker with API access can modify the entire server configuration, redirect traffic, disable TLS, or exfiltrate data through configured backends. To secure the admin API, first, bind it to localhost only if remote access is not needed. For remote access, enable TLS on the admin API endpoint using the api config option. Implement authentication using client certificate verification so that only authorized clients can make API calls. Use network-level security such as VPNs, private networks, or firewall rules to restrict access to the API port. Enable audit logging of all API operations to detect unauthorized configuration changes. Implement configuration versioning and rollback capabilities so that unauthorized changes can be quickly reverted. In high-security environments, consider running the admin API on a separate network interface that is only accessible from the management network, and implement rate limiting on the API to prevent denial-of-service attacks against the configuration management interface.