> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/caddyserver/caddy/llms.txt
> Use this file to discover all available pages before exploring further.
# Caddyfile Configuration
> Learn about Caddy's native Caddyfile format for human-friendly configuration
The Caddyfile is Caddy's native configuration format - a human-friendly alternative to JSON. It provides a simple, intuitive syntax for configuring your web server.
## Overview
The Caddyfile adapter converts Caddyfile syntax to Caddy's native JSON configuration format. This allows you to write configs in a more readable format while maintaining the full power of Caddy's JSON structure.
The Caddyfile is parsed into tokens and then adapted to JSON. Environment variables in `{$ENVIRONMENT_VARIABLE}` notation are replaced before parsing begins.
## Structure
A Caddyfile consists of **server blocks**, which define how Caddy should handle requests for specific sites or addresses.
### Server Blocks
From `caddyconfig/caddyfile/parse.go:753-761`:
```go theme={null}
type ServerBlock struct {
HasBraces bool
Keys []Token
Segments []Segment
IsNamedRoute bool
}
```
Each server block:
* Starts with one or more **addresses** (site addresses or labels)
* Contains **directives** that configure behavior
* Can optionally use curly braces `{}` for multiple directives
```caddyfile Single Site theme={null}
localhost {
respond "Hello World"
}
```
```caddyfile Multiple Sites theme={null}
example.com, www.example.com {
reverse_proxy localhost:8080
}
```
```caddyfile Simple Format theme={null}
localhost
respond "Hello!"
```
## Syntax Rules
### Tokens and Whitespace
From the lexer implementation (`caddyconfig/caddyfile/lexer.go:27-37`):
* **Tokens** are separated by whitespace
* **Quoted strings** can contain whitespace: `"hello world"`
* **Backtick strings** preserve literal content: `` `raw text` ``
* **Comments** start with `#` and continue to end of line
### Quotes and Escaping
```caddyfile theme={null}
# Escape quotes inside quoted strings
respond "He said \"Hello\""
```
```caddyfile theme={null}
# Raw strings - no escaping needed
respond `{"json": "value"}`
```
```caddyfile theme={null}
# Multi-line heredoc syntax
respond <
Hello
HTML
```
Heredoc markers must contain only alphanumeric characters, dashes, and underscores. The closing marker must match the opening marker exactly.
### Environment Variables
Environment variables are replaced during parsing (`caddyconfig/caddyfile/parse.go:67-111`):
```caddyfile theme={null}
# Basic substitution
{$API_KEY}
# With default value
{$PORT:8080}
# In a full example
localhost:{$PORT:2015} {
reverse_proxy {$BACKEND_HOST:localhost:8080}
}
```
## Directives
Directives are keywords that configure Caddy's behavior. From `caddyconfig/caddyfile/parse.go:783-795`:
```go theme={null}
type Segment []Token
// Directive returns the directive name for the segment.
func (s Segment) Directive() string {
if len(s) > 0 {
return s[0].Text
}
return ""
}
```
Directives can:
* Appear on a single line: `respond "OK"`
* Open a block with arguments: `reverse_proxy localhost:8080 { ... }`
* Span multiple lines with line continuation `\`
```caddyfile Logging theme={null}
localhost {
log {
output file ./caddy.log
level INFO
}
}
```
```caddyfile Reverse Proxy theme={null}
example.com {
reverse_proxy localhost:8080 {
header_up Host {upstream_hostport}
health_check {
interval 30s
timeout 5s
}
}
}
```
```caddyfile File Server theme={null}
fileserver.local {
root * /var/www/html
file_server browse
}
```
## Advanced Features
### Snippets
Reusable configuration blocks defined with parentheses (`caddyconfig/caddyfile/parse.go:710-717`):
```caddyfile theme={null}
# Define a snippet
(common-config) {
encode gzip
log
}
# Use the snippet
example.com {
import common-config
reverse_proxy localhost:8080
}
```
### Named Routes
Define reusable route handlers with `&(name)` syntax:
```caddyfile theme={null}
&(api-handler) {
reverse_proxy localhost:3000
}
example.com {
handle /api/* {
invoke api-handler
}
}
```
### Import Directive
Import configurations from other files (`caddyconfig/caddyfile/parse.go:356-579`):
```caddyfile Basic Import theme={null}
import sites/*.conf
```
```caddyfile With Arguments theme={null}
import snippets/ssl.conf example.com
```
```caddyfile sites/api.conf theme={null}
# Can use {args.0} for first argument
{args.0} {
reverse_proxy localhost:3000
}
```
Glob patterns in imports may only contain one wildcard (`*`) to prevent performance issues. Imported files starting with `.` are automatically skipped.
### Matchers
Request matchers filter which requests a directive applies to:
```caddyfile theme={null}
localhost {
# Define a matcher
@api {
path /api/*
header Content-Type application/json
}
# Use the matcher
reverse_proxy @api localhost:3000
# Inline matcher
respond /health 200
}
```
Matchers must be defined within a site block, not globally. Attempting to define matchers globally (e.g., `@matcher ...`) will result in an error.
## Parsing Process
The Caddyfile parsing follows these steps (`caddyconfig/caddyfile/parse.go:30-58`):
1. **Tokenization** - Input is lexed into tokens
2. **Environment Variable Expansion** - `{$VAR}` patterns are replaced
3. **Token Grouping** - Tokens are grouped by server blocks
4. **Directive Parsing** - Each directive is parsed into segments
5. **Import Processing** - Import directives are resolved and inlined
6. **Adaptation** - The structured data is converted to JSON
```go theme={null}
func Parse(filename string, input []byte) ([]ServerBlock, error) {
tokens, err := allTokens(filename, inputCopy)
if err != nil {
return nil, err
}
p := parser{
Dispenser: NewDispenser(tokens),
importGraph: importGraph{
nodes: make(map[string]struct{}),
edges: make(adjacency),
},
}
return p.parseAll()
}
```
## Common Patterns
### HTTPS and TLS
```caddyfile theme={null}
example.com {
# Automatic HTTPS is enabled by default
reverse_proxy localhost:8080
}
# Custom TLS configuration
secure.example.com {
tls cert.pem key.pem
reverse_proxy localhost:8080
}
# Use internal CA for local development
localhost {
tls internal
}
```
### Multiple Routes
```caddyfile theme={null}
example.com {
# Static files
handle /static/* {
root * /var/www/static
file_server
}
# API proxy
handle /api/* {
reverse_proxy localhost:3000
}
# Default handler
handle {
reverse_proxy localhost:8080
}
}
```
### Health Checks and Logging
```caddyfile theme={null}
localhost {
log {
output file ./caddy.access.log
}
log health_check_log {
output file ./caddy.health.log
no_hostname
}
@healthCheck path('/healthz*')
handle @healthCheck {
log_name health_check_log
respond "Healthy"
}
handle {
respond "Hello World"
}
}
```
## Best Practices
**Formatting**: Use `caddy fmt` to automatically format your Caddyfile. The adapter checks formatting and warns if input differs from formatted output.
1. **Use snippets** for common configuration blocks
2. **Organize with imports** for large configurations
3. **Define matchers** for complex routing logic
4. **Add comments** to document your configuration
5. **Test configs** with `caddy validate` before deploying
## Error Handling
Common parsing errors and their solutions:
| Error | Cause | Solution |
| --------------------------- | -------------------------- | ----------------------------- |
| `unexpected token '{'` | Missing space before `{` | Add space: `directive {` |
| `wrong argument count` | Missing required arguments | Check directive documentation |
| `unexpected EOF` | Unclosed block | Add closing `}` |
| `import pattern not found` | Invalid import path | Verify file exists |
| `mismatched heredoc marker` | Incorrect closing marker | Match opening marker exactly |
## See Also
* [JSON Configuration](/config/json) - Caddy's native JSON format
* [Configuration Structure](/config/structure) - Overall config organization
* [HTTP Handlers](/modules/http/handlers) - Available HTTP handlers