Caddyfile Directives

The following directives come standard with Caddy, and can be used in the HTTP Caddyfile:

DirectiveDescription
acme_serverAn embedded ACME server
basicauthEnforces HTTP Basic Authentication
bindCustomize the server’s socket address
encodeEncodes (usually compresses) responses
file_serverServe files from disk
handleA mutually-exclusive group of directives
handle_errorsDefines routes for handling errors
handle_pathLike handle, but strips path prefix
headerSets or removes response headers
importInclude snippets or files
logEnables access/request logging
php_fastcgiServe PHP sites over FastCGI
redirIssues an HTTP redirect to the client
request_headerManipulates request headers
respondWrites a hard-coded response to the client
reverse_proxyA powerful and extensible reverse proxy
rewriteRewrites the request internally
rootSet the path to the site root
routeA group of directives treated literally as single unit
templatesExecute templates on the response
tlsCustomize TLS settings
try_filesRewrite that depends on file existence
uriManipulate the URI

Syntax

The syntax of each directive will look something like this:

  1. directive [<matcher>] <args...> {
  2.     subdirective [<args...>]
  3. }

The <carets> indicate tokens to be substituted by actual values.

The[brackets] indicate optional parameters.

The ellipses ... indicates a continuation, i.e. one or more parameters or lines.

Subdirectives are always optional unless documented otherwise, even though they don’t appear in [brackets].

Matchers

Most—-but not all—-directives accept matcher tokens, which let you filter requests. Matcher tokens are usually optional. If you see this in a directive’s syntax:

  1. [<matcher>]

then the directive accepts a matcher token, letting you filter which requests the directive applies to.

Because matcher tokens all work the same, the various possibilities for the matcher token will not be described on every page, to reduce duplication. Instead, refer to the centralized matcher documentation.

Directive order

Many directives manipulate the HTTP handler chain. The order in which those directives are evaluated matters, so a default ordering is hard-coded into Caddy:

  1. root
  3. header
  5. redir
  6. rewrite
  8. uri
  9. try_files
  11. basicauth
  12. request_header
  13. encode
  14. templates
  16. handle
  17. handle_path
  18. route
  20. respond
  21. reverse_proxy
  22. php_fastcgi
  23. file_server
  24. acme_server

You can override/customize this ordering by using the order global option or the route directive.