The Caddyfile is Caddy's human-readable configuration format that adapts into the native JSON configuration structure. It provides a simplified syntax for defining server blocks, TLS automation, and HTTP middleware while abstracting away the complexity of JSON. The Caddyfile system is implemented as a configuration adapter that transforms text input through lexical analysis, directive processing, and JSON generation.
The Caddyfile configuration system operates as a multi-stage pipeline that transforms text input into Caddy's JSON configuration. The system is implemented in the caddyconfig/caddyfile and caddyconfig/httpcaddyfile packages.
Caddyfile to JSON Adaptation Stages
The adapter is registered in caddyconfig/httpcaddyfile/httptype.go39 as "caddyfile" and processes input through the ServerType.Setup() method at caddyconfig/httpcaddyfile/httptype.go57-362
Sources: caddyconfig/httpcaddyfile/httptype.go38-40 caddyconfig/httpcaddyfile/httptype.go57-362 caddyconfig/caddyfile/parse.go39-58
The Caddyfile system is built around several key types that work together to process configuration:
Core Caddyfile Types and Relationships
The Token type is defined at caddyconfig/caddyfile/lexer.go ServerBlock at caddyconfig/caddyfile/parse.go640-658 and the HTTP-specific types in caddyconfig/httpcaddyfile/
Sources: caddyconfig/caddyfile/dispenser.go26-37 caddyconfig/httpcaddyfile/httptype.go53-54 caddyconfig/httpcaddyfile/directives.go202-211 caddyconfig/httpcaddyfile/directives.go420-435 caddyconfig/httpcaddyfile/directives.go536-540
| Component | Package | Purpose | Key Methods |
|---|---|---|---|
Token | caddyfile | Represents a lexical token | File, Line, Text fields |
Dispenser | caddyfile | Navigates token stream | Next(), NextArg(), NextBlock() |
ServerBlock | caddyfile | Groups tokens by server | Keys, Segments fields |
parser | caddyfile | Parses tokens into blocks | parseAll(), doImport() |
ServerType | httpcaddyfile | Adapts blocks to JSON | Setup() |
Helper | httpcaddyfile | Assists directive parsing | ExtractMatcherSet(), NewRoute() |
ConfigValue | httpcaddyfile | Intermediate config unit | Class, Value fields |
Sources: caddyconfig/caddyfile/dispenser.go26-37 caddyconfig/caddyfile/parse.go113-120 caddyconfig/httpcaddyfile/httptype.go53-54 caddyconfig/httpcaddyfile/directives.go202-211
The Caddyfile transformation follows a structured flow from text input to JSON configuration, with each stage building upon the previous.
ServerType.Setup() Processing Flow
The Setup() method orchestrates all adaptation phases. It processes global options at caddyconfig/httpcaddyfile/httptype.go82-87 evaluates directives at caddyconfig/httpcaddyfile/httptype.go98-172 and builds applications at caddyconfig/httpcaddyfile/httptype.go185-222
Sources: caddyconfig/httpcaddyfile/httptype.go57-362 caddyconfig/httpcaddyfile/httptype.go369-453 caddyconfig/httpcaddyfile/httptype.go531-999
The Caddyfile adapter uses a "pile" pattern to accumulate configuration values from directives. Each serverBlock has a pile map where directives contribute ConfigValue instances grouped by class.
Pile Pattern for Configuration Accumulation
Directives add values to the pile at caddyconfig/httpcaddyfile/httptype.go155-158 and consumers retrieve them by class name (e.g., at caddyconfig/httpcaddyfile/httptype.go759-800 for connection policies).
Sources: caddyconfig/httpcaddyfile/httptype.go76-79 caddyconfig/httpcaddyfile/httptype.go155-158 caddyconfig/httpcaddyfile/httptype.go759-800 caddyconfig/httpcaddyfile/tlsapp.go150-319
Caddy's directive system provides the core mechanism for configuring HTTP request processing. Directives are registered with parser functions and executed in a specific order to build the middleware pipeline.
Directive System Architecture
The directive ordering system in caddyconfig/httpcaddyfile/directives.go32-98 defines the default execution order, which can be modified by plugins or user configuration.
Sources: caddyconfig/httpcaddyfile/directives.go109-138 caddyconfig/httpcaddyfile/directives.go153-187 caddyconfig/httpcaddyfile/directives.go32-98
Caddy includes numerous built-in directives for common HTTP server functionality. Each directive has a specific parser function that converts Caddyfile tokens into configuration values.
| Directive | Parser Function | Configuration Class | Purpose |
|---|---|---|---|
bind | parseBind | bind | Network listener configuration |
tls | parseTLS | tls.connection_policy | TLS connection settings |
root | parseRoot | route | Document root path |
redir | parseRedir | Handler | HTTP redirects |
respond | parseRespond | Handler | Static responses |
handle | parseHandle | Handler | Request handling blocks |
log | parseLog | custom_log | Access logging configuration |
The built-in parsers are registered in caddyconfig/httpcaddyfile/builtins.go38-56 during package initialization.
Sources: caddyconfig/httpcaddyfile/builtins.go38-56 caddyconfig/httpcaddyfile/builtins.go58-84 caddyconfig/httpcaddyfile/builtins.go117-624
The Helper type provides essential utilities for directive parsers, including matcher extraction, route creation, and JSON encoding.
Helper Method Relationships
The Helper methods in caddyconfig/httpcaddyfile/directives.go214-302 provide a consistent interface for directive parsers to interact with the broader configuration system.
Sources: caddyconfig/httpcaddyfile/directives.go202-211 caddyconfig/httpcaddyfile/directives.go214-302
Global options configure Caddy-wide settings that affect all server blocks. They are processed separately from directive parsing and stored in a global options map.
Global Options Processing Flow
Global options are processed in caddyconfig/httpcaddyfile/httptype.go369-453 before any server blocks, allowing them to influence the entire configuration.
Sources: caddyconfig/httpcaddyfile/httptype.go369-453 caddyconfig/httpcaddyfile/options.go32-67
| Option | Parser | Purpose | Configuration Target |
|---|---|---|---|
admin | parseOptAdmin | Admin API configuration | caddy.AdminConfig |
http_port | parseOptHTTPPort | Default HTTP port | caddyhttp.App.HTTPPort |
https_port | parseOptHTTPSPort | Default HTTPS port | caddyhttp.App.HTTPSPort |
email | parseOptSingleString | ACME email address | ACME issuer configuration |
acme_ca | parseOptSingleString | ACME CA endpoint | ACME issuer configuration |
storage | parseOptStorage | Certificate storage backend | caddy.Config.StorageRaw |
debug | parseOptTrue | Debug logging | Logger configuration |
The global options are registered during package initialization in caddyconfig/httpcaddyfile/options.go32-67
Sources: caddyconfig/httpcaddyfile/options.go32-67 caddyconfig/httpcaddyfile/options.go336-369 caddyconfig/httpcaddyfile/options.go516-548
The Caddyfile system automatically generates TLS application configuration based on site addresses and TLS directives. This includes automation policies, certificate loaders, and connection policies.
TLS Configuration Generation Process
The TLS application builder in caddyconfig/httpcaddyfile/tlsapp.go36-534 creates automation policies based on site addresses and user configuration.
Sources: caddyconfig/httpcaddyfile/tlsapp.go36-534 caddyconfig/httpcaddyfile/tlsapp.go621-677 caddyconfig/httpcaddyfile/tlsapp.go682-770
The Caddyfile system supports several advanced features for complex configuration scenarios, including import statements, snippets, named routes, and variable replacement.
Named Route System Architecture
Named routes are extracted in caddyconfig/httpcaddyfile/httptype.go456-528 and can be invoked within server blocks using the invoke directive.
Sources: caddyconfig/httpcaddyfile/httptype.go456-528 caddyconfig/httpcaddyfile/builtins.go888-906
The Caddyfile supports placeholder shorthand replacement that occurs before directive processing. This allows users to define custom shorthand placeholders that expand to full Caddy placeholder syntax.
Variable Replacement Processing
Shorthand replacement is applied in caddyconfig/httpcaddyfile/httptype.go89-101 before directive processing begins.
Sources: caddyconfig/httpcaddyfile/httptype.go89-101 caddyconfig/httpcaddyfile/httptype.go490-492
Refresh this wiki