This document provides an introduction to the Caddy web server, explaining its core design philosophy, key features, and architectural foundations. It covers what makes Caddy unique as a platform, how its modular architecture works, and the different ways to configure it. This page is intended as a starting point for understanding the codebase.
For detailed information about specific subsystems, see:
Caddy is an extensible, production-ready web server platform written in Go `README.md164-165 Unlike traditional web servers that are primarily application binaries, Caddy is fundamentally a platform for running Go applications organized as modules `README.md92 The primary applications that ship with Caddy (like http and tls) are managed by the core runtime, but any Go program can be implemented as a Caddy module and benefit from the unified configuration, lifecycle management, and API `AGENTS.md100-104
Sources: `README.md92 `README.md164-165 `AGENTS.md100-104
Caddy's architecture is built around a powerful module system. Every piece of functionality—from HTTP handlers and matchers to TLS issuers and certificate storage backends—is implemented as a module. This design provides:
New() → JSON unmarshal → Provision() → Validate() → use → Cleanup() `AGENTS.md47Sources: `README.md92 `AGENTS.md33-47
Caddy represents its configuration through a flexible JSON structure. This eliminates the configuration fragmentation found in other web servers. Key configuration components include:
http, tls, and pki that Caddy loads and runs `AGENTS.md102-103Sources: `README.md79-85 `AGENTS.md102-103
Caddy pioneered automatic HTTPS as a default feature `README.md82 It automatically obtains, renews, and manages TLS certificates for all sites. This includes:
Sources: `README.md82-87
Caddy supports three primary configuration methods:
The native configuration format is JSON. This provides complete control and is the format Caddy uses internally `README.md79
The Caddyfile is a human-friendly configuration format that gets adapted to JSON. It is the most common way users interact with Caddy `README.md78 Modules support this by implementing UnmarshalCaddyfile [AGENTS.md:67-92()].
Caddy features a dynamic JSON API that allows for configuration changes at runtime without manual restarts `README.md80
Sources: `README.md78-80 `AGENTS.md67-92
Diagram: Association between Caddy's conceptual module system and specific code interfaces.
Sources: `AGENTS.md33-56 `AGENTS.md100-105
Diagram: Flow from natural language configuration (Caddyfile) to the internal JSON representation used by the Go runtime.
Sources: `AGENTS.md67-92 `AGENTS.md109-112
Caddy is designed to run anywhere with no external dependencies (not even libc) `README.md93 The build system supports a wide array of targets:
The project maintains high quality through automated gates:
golangci-lint `.github/workflows/lint.yml22-64govulncheck `.github/workflows/lint.yml69-84Sources: `README.md93-94 `.github/workflows/cross-build.yml27-37 `.goreleaser.yml44-50 `.github/workflows/ci.yml28-32 `.github/workflows/lint.yml22-84
Caddy's HTTP server is composed of modules like:
zap [AGENTS.md:58-65()].The use of xcaddy allows users to build custom versions of Caddy with specific plugins/modules compiled in `README.md145-148
Sources: `README.md82-91 `README.md145-148 `AGENTS.md25 `AGENTS.md58-65
Refresh this wiki