Caddyfile Tutorial

This tutorial will teach you the basics of the HTTP Caddyfile so that you can quickly and easily produce good-looking, functional site configs.

Objectives:

  • 🔲 First site
  • 🔲 Static file server
  • 🔲 Templates
  • 🔲 Compression
  • 🔲 Multiple sites
  • 🔲 Matchers
  • 🔲 Environment variables
  • 🔲 Comments

Prerequisites:

  • Basic terminal / command line skills
  • Basic text editor skills
  • caddy in your PATH

Create a new text file named Caddyfile (no extension).

The first thing you should type is your site’s address:

  1. localhost

If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like localhost:2015 and change the HTTP port using the http_port Caddyfile option.

Then hit enter and type what you want it to do. For this tutorial, make your Caddyfile look like this:

  1. localhost
  3. respond "Hello, world!"

Save that and run Caddy (since this is a training tutorial, we’ll use the --watch flag so changes to our Caddyfile are applied automatically):

  1. caddy run --watch

If you get permissions errors, try using a higher port in your address (like localhost:2015) and change the HTTP port, or run with elevated privileges.

The first time, you’ll be asked for your password. This is so Caddy can serve your site over HTTPS.

Caddy serves all sites over HTTPS by default as long as a host or IP is part of the site’s address. Automatic HTTPS can be disabled by prefixing the address with http:// explicitly.

First site

Open localhost in your browser and see your web server working, complete with HTTPS!

You might need to restart your browser if you get a certificate error the first time.

That’s not particularly exciting, so let’s change our static response to a file server with directory listings enabled:

  1. localhost
  3. file_server browse

Save your Caddyfile, then refresh your browser tab. You should either see a list of files or an HTML page if there is an index file in the current directory.

Static file server

Adding functionality

Let’s do something interesting with our file server: serve a templated page. Create a new file and paste this into it:

  1. <!DOCTYPE html>
  2. <html>
  3.     <head>
  4.         <title>Caddy tutorial</title>
  5.     </head>
  6.     <body>
  7.         Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}
  8.     </body>
  9. </html>

Save this as caddy.html in the current directory and load it in your browser: https://localhost/caddy.html

The output is:

  1. Page loaded at: {{now | date "Mon Jan 2 15:04:05 MST 2006"}}

Wait a minute. We should see today’s date. Why didn’t it work? It’s because the server hasn’t yet been configured to evaluate templates! Easy to fix, just add a line to the Caddyfile so it looks like this:

  1. localhost
  3. templates
  4. file_server browse

Save that, then reload the browser tab. You should see:

  1. Page loaded at: Wed Jun 17 14:19:06 UTC 2020

With Caddy’s templates module, you can do a lot of useful things with static files, such as including other HTML files, making sub-requests, setting response headers, working with data structures, and more!

Templates

It’s good practice to compress responses with a quick and modern compression algorithm. Let’s enable Gzip and Zstandard support using the encode directive:

  1. localhost
  3. encode zstd gzip
  4. templates
  5. file_server browse

Browsers don’t support Zstandard encodings yet. Hopefully soon!

Compression

That’s the basic process for getting a semi-advanced, production-ready site up and running!

When you’re ready to turn on automatic HTTPS, just replace your site’s address (localhost in our tutorial) with your domain name. See our HTTPS quick-start guide for more information.

Multiple sites

With our current Caddyfile, we can only have the one site definition! Only the first line can be the address(es) of the site, and then all the rest of the file has to be directives for that site.

But it is easy to make it so we can add more sites!

Our Caddyfile so far:

  1. localhost
  3. encode zstd gzip
  4. templates
  5. file_server browse

is equivalent to this one:

  1. localhost {
  2.     encode zstd gzip
  3.     templates
  4.     file_server browse
  5. }

except the second one allows us to add more sites.

By wrapping our site block in curly braces { } we are able to define multiple, different sites in the same Caddyfile.

For example:

  1. :8080 {
  2.     respond "I am 8080"
  3. }
  5. :8081 {
  6.     respond "I am 8081"
  7. }

When wrapping site blocks in curly braces, only addresses appear outside the curly braces and only directives appear inside them.

For multiple sites which share the same configuration, you can add more addresses, for example:

  1. :8080, :8081 {
  2.     ...
  3. }

You can then define as many different sites as you want, as long as each address is unique.

Multiple sites

Matchers

We may want to apply some directives only to certain requests. For example, let’s suppose we want to have both a file server and a reverse proxy, but we obviously can’t do both on every request! Either the file server will write a static file, or the reverse proxy will proxy the request to a backend.

This config will not work like we want:

  1. localhost
  3. file_server
  4. reverse_proxy 127.0.0.1:9005

In practice, we may want to use the reverse proxy only for API requests, i.e. requests with a base path of /api/. This is easy to do by adding a matcher token:

  1. localhost
  3. file_server
  4. reverse_proxy /api/* 127.0.0.1:9005

There; now the reverse proxy will be prioritized for all requests starting with /api/.

The /api/* token we just added is called a matcher token. You can tell it’s a matcher token because it starts with a forward slash / and it appears right after the directive (but you can always look it up in the directive’s docs to be sure).

Matchers are really powerful. You can name matchers and use them like @name to match on more than just the request path! Take a moment to learn more about matchers before continuing!

Matchers

Environment variables

The Caddyfile adapter allows substituting environment variables before the Caddyfile is parsed.

First, set an environment variable (in the same shell that runs Caddy):

  1. export SITE_ADDRESS=localhost:9055

Then you can use it like this in the Caddyfile:

  1. {$SITE_ADDRESS}
  3. file_server

Before the Caddyfile is parsed, it will be expanded to:

  1. localhost:9055
  3. file_server

You can use environment variables anywhere in the Caddyfile, for any number of tokens.

Environment variables

Comments

One last thing that you will find most helpful: if you want to remark or note anything in your Caddyfile, you can use comments, starting with #:

  1. # this starts a comment

Comments

Further reading