caddy server && caddyfile

This page describes how to configure Caddy using the Caddyfile.

Introduction

The term "Caddyfile" describes a text file that changes how Caddy works. It's similar in purpose to httpd.conf or nginx.conf. The Caddyfile file can be named anything, but by default, Caddy will look for a file called Caddyfile in the current directory. You can specify another location for the Caddyfile using the -conf flag:

$ caddy -conf="/path/to/Caddyfile"

If your Caddyfile is within the root of your site, don't worry. Caddy will respond with "404 Not Found" to keep it hidden for you.

Syntax

The Caddyfile always starts with the address of the site to serve:

localhost:2020

After that, each line is expected to start with a valid directive. Directives are keywords that are recognized by Caddy, like gzip:

localhost:2020gzip

Directives usually have one or more arguments after them:

localhost:2020gziplog ../access.log

Some directives may need more configuration than can fit easily on one line. As such, the syntax of a directive may permit you to open a block and set more parameters. The open curly brace must be at the end of a line:

localhost:2020gziplog ../access.logmarkdown /blog { css /blog.css js /scripts.js }

If the directive block is left empty, you should omit the curly braces entirely.

Arguments that contain whitespace must be enclosed in quotes ".

The Caddyfile can also have comments starting with the # character:

# Comments can start a linefoobar # or go at the end

To configure multiple servers (virtual hosts) with a single Caddyfile, you must use curly braces around each site block:

mysite.com { root /www/mysite.com }
sub.mysite.com { root /www/sub.mysite.comgziplog ../access.log }

As with directives, the open curly brace must be at the end of the same line. The closing curly brace must be on its own line.

For sites which share the same configuration, specify multiple addresses:

localhost:2020, https://site.com, http://mysite.com { ... }

Site addresses can also be defined under a specific path, or have wildcards in place of domain labels from the left side:

example.com/static*.example.com

Note that using a path in your site address routes requests by longest matching prefix. If your base path is a directory, you may wish to suffix the path with a forward slash /.

Use of environment variables is allowed in addresses and arguments. They must be enclosed in curly braces, and you can use either Unix or Windows variable formats:

localhost:{$PORT}root {%SITE_ROOT%}

Either syntax works on any platform. A single environment variable does not expand out into multiple arguments/values.

Addresses

Addresses are specified in the form scheme://host:port/path, 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 443). 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 will override the scheme. For example:

:2015 # Host: (any), Port: 2015localhost # Host: localhost, Port: 2015localhost:8080 # Host: localhost, Port: 8080example.com # Host: example.com, Port: 443http://example.com # Host: example.com, Port: 80https://example.com # Host: example.com, Port: 443http://example.com:1234 # Host: example.com, Port: 1234https://example.com:80 # Error! HTTPS on port 80*.example.com # Hosts: *.example.com, Port: 443example.com/foo/ # Host: example.com, Port: 443, Path: /foo//foo/ # Host: (any), Port: 2015, Path: /foo/

Directives

Each line in a server block must start with a valid directive. The order they appear in does not matter. A directive is the first word of a line, and it may be followed by arguments, which are extra values used to configure the directive. A directive may also open a block to specify more parameters.

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.

Path Matching

Some directives accept an argument that specifies a base path to match. A base path is a prefix, so if the URL starts with the base path, it will be a match. For example, a base path of /foo will match requests to /foo, /foo.html, /foobar, and /foo/bar.html. If you want to limit a base path to match a specific directory only, then suffix it with a forward slash like /foo/, which will not match /foobar.