Configuration

Caddy's config is a single JSON document modeled by caddy.Config (caddy.go). This page is a fast reference; the complete generated docs live at caddyserver.com/docs/json.

Top-level shape

{
  "admin": { "...": "see AdminConfig" },
  "logging": { "...": "see Logging" },
  "storage": { "module": "file_system" },
  "apps": {
    "http": { "...": "..." },
    "tls": { "...": "..." },
    "pki": { "...": "..." },
    "events": { "...": "..." }
  }
}

Defined by caddy.Config in caddy.go. Every field is optional except in trivial cases.

Defaults

Setting	Default	Source
Admin listen address	localhost:2019	admin.go: DefaultAdminListen (overridable via CADDY_ADMIN)
Storage module	caddy.storage.file_system	modules/filestorage/filestorage.go
HTTP port	80	modules/caddyhttp/app.go: DefaultHTTPPort
HTTPS port	443	modules/caddyhttp/app.go: DefaultHTTPSPort
ACME issuers (managed certs)	acme (Let's Encrypt) then zerossl (fallback)	modules/caddytls/automation.go
Auto-HTTPS	enabled	modules/caddyhttp/autohttps.go
Local CA name	local	modules/caddypki/ca.go
Default storage path (Linux non-root)	~/.local/share/caddy	storage.go: DataDir
Default storage path (Linux service)	/var/lib/caddy	storage.go: DataDir
Default storage path (macOS)	~/Library/Application Support/Caddy	storage.go: DataDir
Default storage path (Windows)	%AppData%\Caddy	storage.go: DataDir

AdminConfig

Field	Notes
disabled	Turns the admin endpoint off entirely. Once disabled, runtime config changes are impossible.
listen	Address to bind. Overrides CADDY_ADMIN.
enforce_origin	Reject requests with mismatched Host/Origin.
origins	Allowed origins (overrides default of "match listen address").
config	Inline initial config the admin endpoint should serve.
identity	A managed certificate for the admin endpoint itself; needed when binding non-loopback.
remote	Configures a remote control protocol — see admin.go.

Logging

logging.go defines Logging with:

Field	Notes
sink	Where stdlib log.Print lines go (separate from zap).
logs	Map of name → CustomLog. The default log is the fallback for any logger that isn't explicitly captured.

Each CustomLog has writer, encoder, level, sampling, include, exclude fields.

HTTP app

modules/caddyhttp/app.go: App carries:

Field	Notes
http_port, https_port	Default ports (80/443).
grace_period	Graceful shutdown window.
shutdown_delay	Time between marking server unhealthy and shutting down (for load-balancer drain).
servers	Map of server name → Server.

A Server carries:

Field	Notes
listen	One or more network address strings.
routes	The RouteList.
automatic_https	Per-server overrides for the auto-HTTPS pipeline.
tls_connection_policies	Per-server connection policies.
listener_wrappers	List of caddy.listeners.* modules.
read_timeout, read_header_timeout, write_timeout, idle_timeout	Standard net/http timeouts.
max_header_bytes	Same.
experimental_http3	Enable HTTP/3 explicitly (auto-enabled when TLS is present in many configs).
protocols	Restrict to a subset of h1, h2, h2c, h3.
metrics, logs, errors	Per-server hooks.

TLS app

modules/caddytls/tls.go: TLS:

Field	Notes
certificates	Map keyed by loader module name — load_files, load_folders, load_pem, load_storage, automate.
automation	AutomationConfig with policies, on_demand, ocsp_interval, renew_interval.
session_tickets	STEK config.
dns_challenge_options	DNS challenge options.
disable_ocsp_stapling	Self-explanatory.

PKI app

modules/caddypki/pki.go: PKI:

Field	Notes
certificate_authorities	Map of CA ID → CA. The local CA exists by default.

A CA carries name, root_common_name, intermediate_common_name, install_trust, root, intermediate, intermediate_lifetime, storage.

Events app

modules/caddyevents/app.go: App:

Field	Notes
subscriptions	List of Subscription records: events, modules, handlers.

Where to look for full JSON schemas

The runtime documentation at https://caddyserver.com/docs/json/ is generated from the same struct tags this codebase uses, so it always stays in sync with the code. For local exploration, caddy adapt --config Caddyfile --pretty will show you the JSON the adapter would actually run.

Related pages

• Environment variables
• Storage
• Admin API
• Caddyfile feature