Common Caddyfile Patterns
This page demonstrates a few complete and minimal Caddyfile configurations for common use cases. These can be helpful starting points for your own Caddyfile documents.
These are not drop-in solutions; you will have to customize your domain name, ports/sockets, directory paths, etc. They are intended to illustrate some of the most common configuration patterns.
Menu
Static file server
example.com root * /var/www file_server
As usual, the first line is the site address. The root
directive specifies the path to the root of the site (the *
means to match all requests, so as to disambiguate from a path matcher)—change the path to your site if it isn't the current working directory. Finally, we enable the static file server.
Reverse proxy
Proxy all requests:
example.com reverse_proxy localhost:5000
Only proxy requests having a path starting with /api/
and serve static files for everything else:
example.com root * /var/www reverse_proxy /api/* localhost:5000 file_server
PHP
With a PHP FastCGI service running, something like this works for most modern PHP apps:
example.com root * /var/www php_fastcgi /blog/* localhost:9000 file_server
Customize the site root and path matcher accordingly; this example assumes PHP is only in the /blog/
subdirectory—all other requests will be served as static files.
The php_fastcgi
directive is actually just a shortcut for several pieces of configuration.
Redirect www.
subdomain
To add the www.
subdomain with an HTTP redirect:
example.com { redir https://www.example.com{uri} } www.example.com { }
To remove it:
www.example.com { redir https://example.com{uri} } example.com { }
Trailing slashes
You will not usually need to configure this yourself; the file_server
directive will automatically add or remove trailing slashes from requests by way of HTTP redirects, depending on whether the requested resource is a directory or file, respectively.
However, if you need to, you can still enforce trailing slashes with your config. There are two ways to do it: internally or externally.
Internal enforcement
This uses the rewrite
directive. Caddy will rewrite the URI internally to add or remove the trailing slash:
example.com rewrite /add /add/ rewrite /remove/ /remove
Using a rewrite, requests with and without the trailing slash will be the same.
External enforcement
This uses the redir
directive. Caddy will ask the browser to change the URI to add or remove the trailing slash:
example.com redir /add /add/ redir /remove/ /remove
Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource.
Wildcard certificates
If you need to serve multiple subdomains with the same wildcard certificate, the best way to handle them is with a Caddyfile like this, making use of the handle
directive and host
matchers:
*.example.com { tls { dns <provider_name> [<params...>] } @foo host foo.example.com handle @foo { respond "Foo!" } @bar host bar.example.com handle @bar { respond "Bar!" } # Fallback for otherwise unhandled domains handle { abort } }
Note that you must enable the ACME DNS challenge to have Caddy automatically manage wildcard certificates.