Write your first Caddyfile

Shortcuts are fine for experiments. For anything you want to keep, you write a Caddyfile. It’s a small text file that describes your sites.

Why a separate format? Caddy’s native configuration is JSON, and nobody wants to write that by hand. The Caddyfile is a human-friendly layer on top. Caddy converts it to JSON for you when it starts.

The site block

Create a file named Caddyfile in an empty directory:

:8080 {
  respond "hello from a Caddyfile"
}

The first line is the site address. It tells Caddy what to listen for. :8080 means any hostname, port 8080, plain HTTP. Everything inside the braces is the site block, and it describes how that site responds.

respond is a directive. A directive is one instruction inside a site block. This one sends a fixed body back. We’ll meet many more in the next module.

Run it in the foreground

Start Caddy with the file:

caddy run --config Caddyfile

Then test it from another terminal:

curl http://127.0.0.1:8080/

You get hello from a Caddyfile back.

While you’re learning, always run Caddy with caddy run, in the foreground. You see startup errors and log lines the moment they happen. And Ctrl-C stops the process cleanly, instead of leaving a mystery server running in the background.

Why plain HTTP?

You may wonder why :8080 gave us HTTP and not HTTPS. Caddy has no name to issue a certificate for. A port alone isn’t enough.

Change the site address to a hostname like blog.example.com and Caddy switches to automatic HTTPS for that site. That behavior is big enough to get its own module later in this course.

The day-one mistake

Now the mistake everyone makes on day one. You edit the Caddyfile, save it, refresh the browser, and nothing changes.

A running Caddy does not watch the file. Saving does nothing by itself. You have to stop and start the process, or better, tell the running server to pick up the change with caddy reload. We’ll build a safe reload habit in the operations module.

Try it now: change the response text, save, and run curl again. You still get the old text. Press Ctrl-C, start Caddy again, and the new text appears. Once you’ve seen this once, you won’t forget it.