Topics

2. Directives

The HTTP server uses site addresses for . Addresses are specified in the form , where all but one are optional.

The host portion is usually localhost or the domain name. The default port is 2015 (unless the site qualifies for automatic HTTPS, in which case it’s changed to 443 for you). The scheme portion is another way to specify a port. Valid schemes are “http” or “https” which represent, respectively, ports 80 and 443. If both a scheme and port are specified, the port takes precedence. For example (this table assumes automatic HTTPS is applied where it qualifies):

Site addresses must be unique; all configuration for a site must be grouped in the same definition.

Wildcard characters * can be used in a hostname. A wildcard must take the place of an entire domain label: *.example.com is valid but foo*.example.com is not. Hostnames may have more than one wildcard label, but they must be the left-most labels. (Note that to obtain a wildcard certificate, only one wildcard label is allowed; this special case allows automatic HTTPS to stay on.) A site defined as matches only one-label names like “localhost” but not “example.com”. To match all hosts, leave the hostname empty.

Most directives invoke a layer of middleware. Middleware is a small layer in the application that handles HTTP requests and does one thing really well. Middleware are chained together (pre-compiled, if you will) at startup. Only middleware handlers which are invoked from the Caddyfile will be chained in, so small Caddyfiles are very fast and efficient.

The syntax of arguments varies from directive to directive. Some have required arguments, others don’t. Consult the documentation of each directive for their signatures.

In some cases, directives will accept (replaceable values). These are words that are enclosed by curly braces { } and interpreted by the HTTP server at request-time. For example, {query} or . Think of them like variables. These placeholders have no relationship to the environment variables you can use in Caddyfiles, except we borrowed the syntax for familiarity.