Caddy (web Server)

The Caddy web server is an extensible, cross-platform, open-source web server written in Go.

The name "Caddy" refers both to a helper for tedious tasks, and a way to organize multiple parts into a simplified system. At its core, Caddy is an extensible platform for deploying long-running services ("apps") using a single, unified configuration that can be updated on-line with a REST API. Official Caddy distributions ship with a set of standard modules which include HTTP server, TLS automation, and PKI apps. It is best known for its automatic HTTPS features.

Matthew Holt initially began solo development on Caddy in 2014, followed by the first public release in 2015. The software soon became a public collaboration with hundreds of contributors on GitHub. To satisfy requirements from a growing community with a variety of use cases, eventually Caddy was completely rewritten from scratch, and a version 2.0 was released on May 4, 2020.

Caddy binaries are officially distributed for Linux, Windows, macOS, BSD, and other operating systems on a variety of architectures including x86-64, ARM, MIPS, S390X, and PPC64. Official distributions of 32-bit binaries were discontinued, but Caddy can be compiled from source for IA-32 architectures. Packages for Debian, CentOS, RedHat, and Arch Linux are also maintained, as well as an official Docker image.

Architecture

The architecture of Caddy is organized into three main components: a command, the core library, and configuration modules. The command is the extensible interface by which the program is executed; it can also load configuration files, run common modes, manage installed plugins, and offer relevant utility functions. The core library has APIs for loading, unloading, and managing configuration; but it does nothing particularly useful on its own. Most of Caddy's functionality is provided b
modules
which are plugins that extend Caddy's configuration structure; for example, the HTTP server is a module. Caddy modules implement various long-running services, web standards, and other useful features.

Caddy's input is a JSON configuration document which is received through an open socket via a RESTful HTTP API. In the absence of an HTTP client, Caddy's command line interface can be used to load configuration files. Config adapters may be used to convert other configuration formats to JSON. Existing adapters include the Caddyfile, which has first-class support in the command line; and YAML, TOML, NGINX, and several other formats.

When a configuration is received through its administration socket, Caddy decodes the configuration for all the specified modules, and starts running all the app modules. When the app modules are being provisioned, they themselves may load and provision modules that they use. For example, the HTTP server is an app module which uses HTTP handler modules to handle HTTP requests; these handlers might use yet other modules to implement their functionality, and so on. All these modules are provisioned during the config load phase.

Plugins are installed by statically compiling them directly into the Caddy binary. Without plugins, Caddy's native configuration structure only has some basic options for administration and logging. All other functionality must be provided by app modules. Official Caddy distributions ship with dozens of standard modules; others can be added from the project's website, using th
xcaddy command line tool
or by manually compiling a custom build.

HTTP server

Th
HTTP server
is an app module that comes standard with official Caddy distributions. It is primarily used as a static file server and load-balancing reverse proxy. While the basis of Caddy's HTTP features use the implementation found in Go's standard library, a variety enhancements and customizations are available as middleware and exposed through configuration parameters:

* Access logging
* Authentication
* Compression (Gzip and Zstandard) or other encodings
* Custom error handling
* Directory browsing (view file listings in folders)
* FastCGI forwarding
* Hard-coded HTTP responses
* HTTP redirects
* HTTP/1.1, HTTP/2, and HTTP/3 (default for HTTPS)
* HTTP/2 server push
* IPv4 and IPv6 support
* Markdown rendering
* Network interface customization
* Request matchers
* Request size limits (headers and body)
* Reverse proxy with load balancing, health checks, and retries
* Static files
* Templates (similar to Server-Side Includes)
* Timeouts
* TLS by default (TLS 1.3, including temporary support for older versions)
* URL rewriting
* Variables and maps
* Virtual hosts (multiple sites on same socket)
* WebSockets
* Zero-downtime, graceful reloads

Caddy's HTTP server handles requests according to configured routes in a middleware pattern. Routes are defined in a list, and each route that matches the request is applied to the middleware chain in order. Requests can be matched from a variety of parameters including HTTP method, hostname, remote address, header fields, path, query string, protocol, variable values, file existence, CEL expressions, and others as given by plugins. Once matched, handler modules are invoked, which may include a file server, a rewrite middleware, the reverse proxy, rate limiting, header manipulation, and template rendering, among other functions. Additionally, routes can be defined to be mutually exclusive to other routes, or terminal which ends the handler chain.

By default, TLS is used automatically if any routes have a non-empty host matcher. These are assumed to be site names or IP addresses that Caddy is serving, so Caddy will automatically procure and renew certificates for the configured hostnames and IP addresses. When automatic HTTPS is activated in this manner, Caddy will also redirect HTTP requests to their equivalent HTTPS location.

TLS automation

Th
TLS app
comes standard with official Caddy distributions. It acts as a TLS server and is designed for automation. Caddy's TLS defaults are considered safe and modern. In terms of securing private keys, Caddy is not vulnerable to memory safety vulnerabilities such as Heartbleed because it is written in Go.
One of the primary purposes of this module is to load TLS certificates into memory so they can be served to complete TLS handshakes. Certificate and key files may be loaded manually into the server, but they are usually automated by specifying subject names. If loaded manually, Caddy does not auto-renew them. If automated, this app will automatically obtain and renew a certificate for each subject name. A given certificate will be automated according to the first matching automation policy for its subject name (typically a domain name or IP address). An automation policy consists of issuers and various certificate and management options such as key type, where to store the certificate, whether to manage the certificate "on-demand", and OCSP options. These automation features work for server certificates as well as client certificates. Wildcard certificates are supported.

An issuer is a source for a certificate, and is typically an ACME certificate authority. Caddy fully supports the ACME protocol including the HTTP, TLS-ALPN, and DNS challenges, External Account Binding (EAB), multiple certificate chains, and smart retry heuristics. Caddy can also be its own issuer with its embedded PKI facilities. Multiple issuers may be specified for redundancy; if one fails to offer a certificate, the next will be tried.

TLS certificates can be stored in a configurable storage backend, which is by default the local file system. Plugins exist for other kinds of storage backends such as databases. Caddy instances which are configured to use the same storage backend will automatically act as part of a cluster and share certificate and OCSP assets, including coordinating the obtaining and renewal of certificates.

Typically, certificates are managed at startup when the config is loaded. However, Caddy supports a mode of automation calle
On-Demand TLS
which defers certificate operations until the very moment the certificate is needed, during the TLS handshake. This is suitable for use cases where the site owner does not control the domain names served by the server. In order to be safe from abuse on a public network, the site owner should configure an endpoint that Caddy will query to ask if a certificate may be obtained for the given Server Name Indication (SNI) in the handshake.

Caddy implements OCSP stapling by default. All loaded certificates which specify an OCSP responder in the Authority Information Access extension will have their OCSP response stapled, cached, and refreshed automatically as needed. If an OCSP response indicates a status of Revoked for a managed certificate, Caddy will automatically attempt to replace the certificate with a new one.

When serving TLS, Caddy will automatically rotate session ticket keys periodically to help preserve perfect forward secrecy. These keys can also be stored in a configurable backend and used by a cluster of instances for improved performance in a distributed fashion.

PKI facilities

Th
PKI app
comes standard with official Caddy distributions. Its primary purpose is to manage certificate authorities (CAs) that can sign certificates. Each CA consists of a root and intermediate key pair, which are persisted to storage. The CA identifier, common name, and key information can be customized in this module's configuration. This app is primarily used by other modules when self-signed certificates are needed.

Financial backing

Until 2016, Caddy operated completely by volunteer effort without any financial support, simply accepting occasional donations from the website. As the community grew and demands on development time and infrastructure increased, it was determined that the project needed to be funded. Light Code Labs, LLC was formed to become the legal entity behind Caddy. With legal legitimacy, the first form of financial support came from a Mozilla Open Source Support (MOSS) program award in 2016. This provided funding for 6 months of development work, and was crucial to Caddy's growth at that stage.

Seeking longer-term sustainability, Light Code Labs soon offered two optional products for businesses and professionals: the Engineering Package and Sponsorship, which granted access to developer resources and publicity for customers. With only little success, it was decided that phasing out those products in favor of distributing official binaries intended for commercial use under a proprietary license could increase sustainability by requiring companies to pay for the right to use specially-offered, pre-compiled Caddy binaries that powered their business. This would leave Caddy's source code under the Apache license for anyone to use freely, while still being able to gain some financial backing from able companies as customers.

Although more sustainable, this approach was widely viewed with disdain, and was met with confusion and controversy over the next few years. Product offerings were adjusted to clarify terms, gain the respect of the community, and better capture the commercial sector. In 2019, Light Code Labs entered into a partnership with Ardan Studios to design and build an all-new version of Caddy which could be utilized more readily in enterprise environments: Caddy Enterprise. However, on October 3, 2019, the two companies announced plans to instead revert all plans for commercial licenses, which included:

* reaffirming that Caddy will continue to be, and always has been, an Apache-licensed open source project,
* dropping all proprietary licensing and removing the business use case restrictions from official binaries,
* dropping plans for enterprise-only features,
* rebranding the new version of Caddy simply as Caddy 2,
* and eliminating all other existing business-only products, subscriptions, and services.

Ardan Studios would proceed to offer professional training, Caddy development, and enterprise support to businesses, and provided funding for full-time open source development of the Caddy project for almost one year. Shortly before the initial release of Caddy 2, an agreement was signed by Light Code Labs and Ardan Studios for the Caddy project (along wit
CertMagic
Caddy's core TLS automation library) to be acquired by API Layer, GmbH (later Stack Holdings, GmbH). The transfer of ownership was announced later that year in September 2020, along with a two-year development contract. This exchange did not alter the open source status or development cycle of the project.

As of 2021, necessary financial support for the Caddy project continues by sponsorships through GitHub Sponsors, with ZeroSSL (a Stack Holdings company) being the primary, executive sponsor.

Influence

Caddy has been used as the basis for other software projects and commercial services, and its reach extends into academic research and industry discussion.

CoreDNS was created by Miek Gieben from a fork of Caddy v1 which was modified to serve DNS instead of HTTPS. It leveraged Caddy's Caddyfile configuration format, plugin architecture, and use of the Go language.

Cloudflare implemented a machine-in-the-middle (MITM) detection service originally based on Caddy using its native MITM detection capabilities. The same company also used Caddy to serve an experimental TLS 1.3 implementation while participating in the formation of the final TLS 1.3 specification.

Let's Encrypt considers Caddy's implementation of ACME to be the gold standard of ACME clients, and Caddy has become a model for similar software to follow.

Caddy has participated in a number of academic papers and enabled various Internet research. It has been referenced in relation to:

* validating the feasibility of the ACME protocol in production servers,
* Internet-scale deployment of QUIC,
* a test framework for cloud failover mechanisms,
* measuring the security harm of TLS cryptography shortcuts,
* advocating the case for secure-by-default TLS,
* and improving the usability of deploying HTTPS.

References

External links

*
*{{GitHub, caddyserver/caddy

Cross-platform free software
Free proxy servers
Free web server software
Reverse proxy
Free software programmed in Go