Introduction to Caddy

Relevant source files

• .github/CONTRIBUTING.md
• .github/SECURITY.md
• .github/workflows/ci.yml
• .github/workflows/cross-build.yml
• .github/workflows/lint.yml
• .github/workflows/release.yml
• .golangci.yml
• .goreleaser.yml
• AGENTS.md
• README.md

Purpose and Scope

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:

• Core architecture and module system: Core Architecture
• HTTP server implementation: HTTP Server
• TLS and certificate management: TLS and HTTPS
• Configuration formats: Caddyfile Configuration

---

What is Caddy

Caddy is an extensible, production-ready web server platform written in Go README.md:164-165. Unlike traditional web servers that are primarily application binaries, Caddy is fundamentally a platform for running Go applications organized as modules README.md:92. 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.md:100-104.

Sources: README.md:92, README.md:164-165, AGENTS.md:100-104

---

Design Philosophy

Everything is a Module

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:

• Extensibility without bloat: Core functionality remains lean while allowing unlimited extension README.md:92.
• Consistent lifecycle: All modules follow the same lifecycle: New() → JSON unmarshal → Provision() → Validate() → use → Cleanup() AGENTS.md:47.
• Modular Registration: Modules register themselves during package initialization AGENTS.md:33-45.

Sources: README.md:92, AGENTS.md:33-47

Configuration as a Single Document

Caddy represents its configuration through a flexible JSON structure. This eliminates the configuration fragmentation found in other web servers. Key configuration components include:

• Native JSON: The primary configuration format README.md:79.
• Storage backend: Configuration for where Caddy stores certificates and persistent data README.md:83-85.
• Applications: Top-level modules like http, tls, and pki that Caddy loads and runs AGENTS.md:102-103.

Sources: README.md:79-85, AGENTS.md:102-103

Automatic HTTPS by Default

Caddy pioneered automatic HTTPS as a default feature README.md:82. It automatically obtains, renews, and manages TLS certificates for all sites. This includes:

• Automatic certificate issuance from ZeroSSL and Let's Encrypt for public names README.md:83.
• Fully-managed local CA for internal names and IPs README.md:84.
• Support for Encrypted ClientHello (ECH) and multi-issuer fallback README.md:86-87.

Sources: README.md:82-87

---

Configuration Approaches

Caddy supports three primary configuration methods:

Native JSON Configuration

The native configuration format is JSON. This provides complete control and is the format Caddy uses internally README.md:79.

Caddyfile

The Caddyfile is a human-friendly configuration format that gets adapted to JSON. It is the most common way users interact with Caddy README.md:78. Modules support this by implementing UnmarshalCaddyfile [AGENTS.md:67-92()].

Admin API

Caddy features a dynamic JSON API that allows for configuration changes at runtime without manual restarts README.md:80.

Sources: README.md:78-80, AGENTS.md:67-92

---

Core Architecture Overview

Primary Code Entities and Their Relationships

Diagram: Association between Caddy's conceptual module system and specific code interfaces.

Sources: AGENTS.md:33-56, AGENTS.md:100-105

Configuration Adaptation Flow

Diagram: Flow from natural language configuration (Caddyfile) to the internal JSON representation used by the Go runtime.

Sources: AGENTS.md:67-92, AGENTS.md:109-112

---

Build and Deployment

Cross-Platform Support

Caddy is designed to run anywhere with no external dependencies (not even libc) README.md:93. The build system supports a wide array of targets:

• OS: Linux, macOS, Windows, FreeBSD, OpenBSD, Solaris, AIX, and more .github/workflows/cross-build.yml:27-37.
• Architectures: amd64, arm, arm64, s390x, ppc64le, riscv64 .goreleaser.yml:44-50.

Continuous Integration (CI)

The project maintains high quality through automated gates:

• Testing: Tests run on Linux, Mac, and Windows via GitHub Actions .github/workflows/ci.yml:28-32.
• Linting: Strict linting via golangci-lint .github/workflows/lint.yml:22-64.
• Security: Vulnerability checks using govulncheck .github/workflows/lint.yml:69-84.

Sources: README.md:93-94, .github/workflows/cross-build.yml:27-37, .goreleaser.yml:44-50, .github/workflows/ci.yml:28-32, .github/workflows/lint.yml:22-84

---

Key Features

Modular HTTP Pipeline

Caddy's HTTP server is composed of modules like:

• Reverse Proxy: Load balancing, health checks, and multiple transports README.md:82-91.
• Static File Server: Efficient file serving with precompression support AGENTS.md:25.
• Logging: Structured logging using zap [AGENTS.md:58-65()].

Extensibility

The use of xcaddy allows users to build custom versions of Caddy with specific plugins/modules compiled in README.md:145-148.

Sources: README.md:82-91, README.md:145-148, AGENTS.md:25, AGENTS.md:58-65