我的书签
添加书签
移除书签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
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).
Windows
macOS
Linux
Right-click the .zip file and choose “Extract All”. Choose any folder to extract into, just don’t lose track of it. You can delete it when we’re done.
Double-click the .zip file to extract it, or run this command: unzip caddy*.zip caddy
Run this command: tar -xzf caddy*.tar.gz caddy
Next, we will move the Caddy binary into a folder where we can execute it easily.
Windows
macOS
Linux
Move the executable to any folder that’s easy to get at. For example, C:\Caddy.
Any $PATH location will do: mv ./caddy /usr/local/bin If you get permission denied errors, you’ll need to run with sudo.
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:
cd path/to/my/site
And run Caddy:
Windows
macOS
Linux
Assuming you put the .exe file in C:\Caddy, run: C:\Caddy\caddy.exe
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):
- The site is being served on port 2015, not 80 (the standard HTTP port).
- 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:
Windows
macOS
Linux
C:\Caddy\caddy.exe -host example.com
caddy -host example.com
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:
Windows
macOS
Linux
Right-click cmd.exe and click “Run as Administrator”. Then run Caddy again: C:\Caddy\caddy.exe -host example.com
Use sudo to run Caddy as root: sudo caddy -host example.com
On a real server, you would consider using setcap like this: sudo setcap cap_net_bind_service=+ep $(which caddy) $ caddy -host example.com But for your own computer, running Caddy with sudo probably fine: sudo caddy -host example.com
If you got your permissions right and run Caddy again, you’ll see:
Activating privacy features... done. https://example.com http://example.com
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:
Windows
macOS
Linux
Make a text file in your site’s folder called Caddyfile (no .txt extension), and put one line in it (use your actual domain name, or localhost): example.com
Use your actual domain name (or localhost): echo example.com > Caddyfile
Caddy will automatically find that file when you start it:
Windows
macOS
Linux
caddy
caddy
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:
Windows
macOS
Linux
caddy -conf C:\path\to\Caddyfile
caddy -conf ../path/to/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.
