User Guide

Beginner Tutorial

This tutorial will help you install, run, and configure Caddy for your first time. It assumes you have never used a web server before! (If you have, do the quick start.) Although Caddy is very easy to use, it is still expected that you are already familiar with using your machine:

• Extracting, moving, and renaming files
• Managing users and file permissions
• Using the terminal or command line
• Configuring your firewall

With these prerequisites, you're ready to go.

Topics

1. Download
2. Install
3. Run
4. Configure

Download

Download Caddy from the download page. You can get Caddy for nearly any OS and architecture. Caddy's download page is unique from other web servers: it lets you customize your build with plugins.

For this tutorial, you don't need any plugins.

Sometimes our build server undergoes maintenance. If the download page is down, you can always download the latest release from GitHub (without plugins).

Install

The file you downloaded is a compressed archive. You'll want to extract the Caddy binary (executable file).

Next, we will move the Caddy binary into a folder where we can execute it easily.

Now Caddy is at our fingertips. Let's run it!

Run

By default, Caddy will use the current directory (the directory it is being executed from, not the folder where the binary lives) as the root of the site. This makes it easy to work on sites locally!

Using the terminal or command line, change into the folder where your site is:

And run Caddy:

Load http://localhost:2015 in your browser. If you see a 404 error, then Caddy is working but your site is missing an index file.

You can quit Caddy by pressing Ctrl+C. It will terminate as gracefully as possible.

Configure

Your site is already fit for production! But it's not ideal, because we happen to running on localhost (your home computer):

1. The site is being served on port 2015, not 80 (the standard HTTP port).
2. The site isn't protected with HTTPS.

It's easy to fix both of these simply by telling Caddy the name of the site to serve. By "name", we mean a domain name. We'll use example.com here, but you use your real domain. This next part is only going to work if your computer is accessible from the wider Internet on ports 80 and 443, and your domain name points to the computer you're on. If not, or you don't have a real domain name, then use localhost as your domain name.

The name of the site is also called the host or hostname. One way to specify the host is with a command line option:

The first time you run Caddy with a real hostname (not localhost), you'll be asked to enter your email address. This is because Caddy needs to verify you own the domain and to store the certificate safely on disk for you.

After submitting your email address, do you see an error like permission denied? That's because Caddy is trying to bind to ports 80 and 443 for a real site, but doing this requires root or Administrator privileges:

If you got your permissions right and run Caddy again, you'll see:

Using a real domain name triggers Caddy's privacy features, which operate on ports 80 and 443. If you're just using localhost as your hostname, Caddy continues to serve on port 2015 unless you change it with the -port option.

The command line interface is great for quick Caddy configurations. But what if you want to reuse the same config every time? It's easy with the Caddyfile.

The Caddyfile is a text file that tells Caddy how to serve. It usually lives next to your site. Let's make one:

Caddy will automatically find that file when you start it:

This works because the first line of a Caddyfile is always the address (or name) of the site to serve.

If the Caddyfile is ever in another directory than the current one, you can tell Caddy where to get the Caddyfile:

You almost know enough to be dangerous. Next, learn how to wield the Caddyfile. You'll love how easy it is to write.

Or go to docs index.