mirrors/caddy-website
1
0
Fork 0
mirror of https://github.com/caddyserver/website.git synced 2025-05-06 11:47:12 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Getting Started -> Intro, new Getting Started

Browse source 
Several other smaller improvements and clarifications.
This commit is contained in:
Matthew Holt 2022-09-10 14:20:11 -06:00
parent 3fe4d09713
commit 1965a6b120
No known key found for this signature in database
GPG key ID: 2A349DD577D586A5
8 changed files with 529 additions and 238 deletions
Download patch file Download diff file Expand all files Collapse all files

2
src/docs/markdown/automatic-https.md
View file

@ -122,6 +122,8 @@ In addition, hostnames qualify for publicly-trusted certificates if they:
## Local HTTPS
Caddy uses HTTPS automatically for all sites with a host (domain, IP, or hostname) specified, including internal and local hosts. Some hosts are either not public (e.g. `127.0.0.1`, `localhost`) or do not generally qualify for publicly-trusted certificates (e.g. IP addresses -- you can get certificates for them, but only from some CAs). These are still served over HTTPS unless disabled.
To serve non-public sites over HTTPS, Caddy generates its own certificate authority (CA) and uses it to sign certificates. The trust chain consists of a root and intermediate certificate. Leaf certificates are signed by the intermediate. They are stored in [Caddy's data directory](/docs/conventions#data-directory) at `pki/authorities/local`.
Caddy's local CA is powered by [Smallstep libraries](https://smallstep.com/certificates/).

32
src/docs/markdown/caddyfile/concepts.md
View file

@ -27,7 +27,7 @@ Key points:
- An optional [**global options block**](#global-options) can be the very first thing in the file.
- Otherwise, the first line of the Caddyfile is **always** the [address(es)](#addresses) of the site to serve.
- All [directives](#directives) and [matchers](#matchers) **must** go in a site block. There is no global scope or inheritence across site blocks.
- If there is **only one site block**, its curly braces `{ }` are optional.
- If there is only one site block, its curly braces `{ }` are optional.
A Caddyfile consists of at least one or more site blocks, which always starts with one or more [addresses](#addresses) for the site. Any directives appearing before the address will be confusing to the parser.
@ -41,7 +41,7 @@ Opening and closing a **block** is done with curly braces:
}
```
- The open curly brace `{` must be at the end of its line.
- The open curly brace `{` must be at the end of its line and preceded by a space.
- The close curly brace `}` must be on its own line.
When there is only one site block, the curly braces (and indentation) are optional. This is for convenience to quickly define a single site, for example, this:
@ -82,7 +82,7 @@ If a request matches multiple site blocks, the site block with the most specific
### Directives
[**Directives**](/docs/caddyfile/directives) are keywords which customize how the site is served. For example, a complete file server config might look like this:
[**Directives**](/docs/caddyfile/directives) are functional keywords which customize how the site is served. They **must** appear within site blocks. For example, a complete file server config might look like this:
```caddy
localhost
@ -102,9 +102,7 @@ In these examples, [`file_server`](/docs/caddyfile/directives/file_server) and [
In the second example, `localhost:9000` is an **argument** because it appears on the same line after the directive.
Note that when the Caddyfile is adapted, directives are sorted according to a specific default [directive order](/docs/caddyfile/directives#directive-order).
**Subdirectives** can appear in directive blocks:
Sometimes directives can open their own blocks. **Subdirectives** appear on the beginning of each line within directive blocks:
```caddy
localhost
@ -116,6 +114,10 @@ reverse_proxy localhost:9000 localhost:9001 {
Here, `lb_policy` is a subdirective to [`reverse_proxy`](/docs/caddyfile/directives/reverse_proxy) (it sets the load balancing policy to use between backends).
**Unless otherwise documented, directives cannot be used within other directive blocks.** For example, `basicauth` cannot be used within `file_server` because the file server does not know how to do authentication; but you can use directives within [`route`](/docs/caddyfile/directives/route), [`handle`](/docs/caddyfile/directives/handle), and [`handle_path`](/docs/caddyfile/directives/handle_path) blocks because they are specifically designed to group directives together.
Note that when the HTTP Caddyfile is adapted, HTTP handler directives are sorted according to a specific default [directive order](/docs/caddyfile/directives#directive-order) unless in a [`route`](/docs/caddyfile/directives/route) block, so the order of appearance of the directives does not matter except in `route` blocks.
### Tokens and quotes
@ -141,19 +143,19 @@ Quotes can be escaped if you need to use quotes in quoted tokens, too:
directive "\"abc def\""
```
Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are possible:
To avoid escaping quotes, you can instead use backticks <code>\` \`</code> to enclose tokens; for example:
```caddy-d
directive `{"foo": "bar"}`
```
Inside quoted tokens, all other characters are treated literally, including spaces, tabs, and newlines. Multi-line tokens are thus possible:
```caddy-d
directive "first line
second line"
```
You can also use a backtick <code>`</code> to quote tokens; these are convenient when tokens themselves contain double quotes, e.g. JSON text:
```caddy-d
directive `{"foo": "bar"}`
```
## Addresses
@ -208,9 +210,9 @@ By default, sites bind on all network interfaces. If you wish to override this,
## Matchers
By default, a directive that injects an HTTP handler applies to all requests (unless otherwise documented).
HTTP handler directives apply to all requests by default (unless otherwise documented).
Request matchers can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a certain directive applies to.
[Request matchers](/docs/caddyfile/matchers) can be used to classify requests by a given criteria. This concept originates in the [underlying JSON](/docs/json/apps/http/servers/routes/match/) structure, and it's important to know how to use them in the Caddyfile. With matchers, you can specify exactly which requests a certain directive applies to.
For directives that support matchers, the first argument after the directive is the **matcher token**. Here are some examples:

2
src/docs/markdown/caddyfile/directives.md
View file

@ -29,6 +29,8 @@ title: Caddyfile Directives
# Caddyfile Directives
Directives are functional keywords that appear within site [blocks](/docs/caddyfile/concepts#blocks). Sometimes, they may open blocks of their own which can contain _subdirectives_, but directives **cannot** be used within other directives unless noted. For example, you can't use `basicauth` inside a `file_server` block, because `file_server` does not know how to do authentication. However, you _may_ use some directives within special directive blocks like `handle` and `route` because they are specifically designed to group HTTP handler directives.
The following directives come standard with Caddy, and can be used in the HTTP Caddyfile:
<div id="directive-table">

371
src/docs/markdown/getting-started.md
View file

@ -4,274 +4,273 @@ title: "Getting Started"
# Getting Started
Welcome to Caddy! This tutorial will explore the basics of using Caddy and help you get familiar with it at a high level.
This guide will help you get a site up and running with Caddy on **Linux** in a matter of minutes, but it is _not the only way_ to do it. There are many ways you can [download](/download), [install](/docs/install), [configure](/docs/introduction), and [run](/docs/running) Caddy. **If you are already comfortable with setting up services using systemd, jump to [Introduction](/docs/introduction).**
You can jump out of this tutorial at any time when you feel like you know what to do next.
**Objectives:**
- 🔲 Run the daemon
- 🔲 Try the API
- 🔲 Give Caddy a config
- 🔲 Test config
- 🔲 Make a Caddyfile
- 🔲 Use the config adapter
- 🔲 Start with an initial config
- 🔲 Compare JSON and Caddyfile
- 🔲 Compare API and config files
- 🔲 Run in the background
- 🔲 Zero-downtime config reload
- 🔲 Install Caddy as a service
- 🔲 Discover the unit configuration
- 🔲 Prepare your site
- 🔲 Serve your site over HTTPS
- 🔲 Add a reverse proxy
- 🔲 Learn how to troubleshoot problems
**Prerequisites:**
- Basic terminal / command line skills
- Basic text editor skills
- `caddy` and `curl` in your PATH
- A computer where you have administrator, root, or sudo privileges
- Know how to use a terminal / command line
- Familiarity with Unix permissions
- Be comfortable editing text files
- A registered domain name
---
**If you [installed Caddy](/docs/install) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.**
First, ensure no other web servers are running on your machine (to avoid port-binding conflicts).
Let's start by running it:
<pre><code class="cmd bash">caddy</code></pre>
Oops; without a subcommand, the `caddy` command only displays help text. You can use this any time you forget what to do.
To start Caddy as a daemon, use the `run` subcommand:
<pre><code class="cmd bash">caddy run</code></pre>
<aside class="complete">Run the daemon</aside>
This blocks forever, but what is it doing? At the moment... nothing. By default, Caddy's configuration ("config") is blank. We can verify this using the [admin API](/docs/api) in another terminal:
<pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
**[Install Caddy](/docs/install) by following the instructions for your system.** For example, if you're on Ubuntu, follow the steps that use `apt`; on Fedora, use `dnf`; etc. If a package isn't available for your distro, you can also [manually install Caddy as a service](/docs/running) on any Linux machine that has systemd.
<aside class="tip">
This is **not** your website: the administration endpoint at localhost:2019 is used for controlling Caddy and is restricted to localhost by default.
All you really need to run Caddy is the executable file itself. "Installing" Caddy could be defined simply as putting Caddy in your PATH. But installing Caddy _as a service_ is best practice for production systems because generally, a service keeps the process running after reboots, implements a tighter permissions/security model, and centralizes logging.
</aside>
Verify that the Caddy service is running:
<aside class="complete">Try the API</aside>
<pre><code class="cmd bash">systemctl status caddy</code></pre>
We can make Caddy useful by giving it a config. This can be done many ways, but we'll start by making a POST request to the [/load](/docs/api#post-load) endpoint using `curl` in the next section.
You should see output like this:
```plain
● caddy.service - Caddy
Loaded: loaded (/lib/systemd/system/caddy.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2022-09-06 21:15:31 MDT; 1 day 1h ago
...
```
Ensure it says "enabled" and "active (running)" -- these are crucial for production. (Enabled means the service will be started automatically after a reboot.)
## Your first config
If Caddy failed to start, the most likely cause is you have another web server running. The output will also show the most recent log lines which you can inspect for error messages. After resolving the issue, run `sudo systemctl start caddy` to try again.
To prepare our request, we need to make a config. At its core, Caddy's configuration is simply a [JSON document](/docs/json/).
<aside class="complete">Install Caddy as a service</aside>
Save this to a JSON file (e.g. `caddy.json`):
How is your web server's service configured? A unit file (ending with `.service`) contains the service configuration. The [default unit file we provide](https://github.com/caddyserver/dist/blob/master/init/caddy.service) runs Caddy with a configuration file. It tells you the precise `caddy` command, the location of the Caddy config, special permissions, the process' working directory, and any environment variables passed to the process.
```json
{
"apps": {
"http": {
"servers": {
"example": {
"listen": [":2015"],
"routes": [
{
"handle": [{
"handler": "static_response",
"body": "Hello, world!"
}]
}
]
}
}
}
}
Notice the output above shows the location of the `caddy.service` file. Let's print its contents:
<pre><code class="cmd bash">cat /lib/systemd/system/caddy.service</code></pre>
You will see the `ExecStart=` line, which defines the command to execute. The `ExecReload=` line the command that is executed to reload the configuration when you do `systemctl reload caddy`. The `--config` flag in the `caddy` commands is the location of the Caddy configuration file. Take note of this, as its location varies by platform (but it is often `/etc/caddy/Caddyfile`).
<aside class="complete">Discover the unit configuration</aside>
- **If you are running Caddy locally on your own computer:** you can go to [http://localhost](http://localhost) in your browser and you should see a slanted page telling you how to get rid of the slanted page. (It's our default "welcome" page to let you know the server is working. 🙃) You can follow those instructions if you want; they're similar to this tutorial but more succinct.
- **If you are setting up a remote server:** you can either run `curl localhost` on that machine, or you can navigate to the IP address of your server in your web browser or run `curl <ip>` locally.
## Your first site
Copy your site's static files (HTML, CSS, JS, images, etc.) into a folder that is accessible to the `caddy` user/group. This folder is called the _site root_. In production, it's often `/var/www/html` and we'll use that path in this tutorial. Expect that everything in this directory will become publicly accessible.
Once your site files are in place, make sure Caddy can access them; for example:
<pre><code class="cmd bash">chown -R caddy:caddy /var/www/html</code></pre>
Next, we need to tell Caddy where to find the site root. Open the configuration file you noted above (e.g. `/etc/caddy/Caddyfile`) and change its `root` directive to point to your site's directory:
```caddy
:80 {
root * /var/www/html
file_server
}
```
<aside class="tip">
You do not have to use config files, but we are for this tutorial. Caddy's [admin API](/docs/api) is designed for use by other programs or scripts.
The permissions on this Caddyfile are restricted to prevent tampering and accidental changes. To save changes to this Caddyfile, you may need to open it as root (`sudo`).
</aside>
Be sure to save the changes.
Then upload it:
Since we changed the Caddyfile, we need to load the new config into Caddy:
<pre><code class="cmd bash">curl localhost:2019/load \
-H "Content-Type: application/json" \
-d @caddy.json
</code></pre>
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
<aside class="complete">Give Caddy a config</aside>
- **If that failed:** double-check your Caddyfile. Spaces are significant; make sure it looks tidy. Check file and folder permissions. Ensure the path is correct.
We can verify that Caddy applied our new config with another GET request:
- **If that succeeded:** open your browser to [http://localhost](http://localhost) again and you should see your site! If you don't, make sure the file permissions are correct and that you have an index file in your site root (e.g. `index.html`).
<pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
<aside class="tip">
Test that it works by going to [localhost:2015](http://localhost:2015) in your browser or use `curl`:
Advanced sites often have additional configuration in production to [set headers](/docs/caddyfile/directives/header), enable [compression](/docs/caddyfile/directives/encode) or use compressed [sidecar files](/docs/caddyfile/directives/file_server), and [enable HTTP request logging](/docs/caddyfile/directives/log).
<pre><code class="cmd"><span class="bash">curl localhost:2015</span>
Hello, world!</code></pre>
</aside>
If you see _Hello, world!_, then congrats -- it's working! It's always a good idea to make sure your config works as you expect, especially before deploying into production.
<aside class="complete">Test config</aside>
<aside class="complete">Prepare your site</aside>
## Your first Caddyfile
## HTTPS
That was _kind of a lot of work_ just for Hello World.
Given a domain name, Caddy will obtain a TLS certificate for your site and keep it renewed while it stays running. It's all [automatic](/docs/automatic-https)!
Another way to configure Caddy is with the [**Caddyfile**](/docs/caddyfile). The same config we wrote in JSON above can be expressed simply as:
Before continuing, **point your domain to your server's IP address.** This means setting the value of your domain's A/AAAA record(s) to the public IP address of your server.
Usually this means logging into your DNS provider and creating or changing the A (IPv4) and/or AAAA (IPv6) record for your domain (it can be a subdomain). We'll use `example.com` for this tutorial. Verify it has been set by running `dig example.com`.
Then, **verify that your server's IP is publicly routable on the standard Web ports (80 and 443).** Ensure there are no firewalls or routers blocking these ports. On a home network, you may need to forward those ports to your machine (just be aware that your machine will become publicly accessible on those ports).
Once your DNS and network infrastructure are properly configured, **all you need to do is replace `:80` in the Caddyfile with your domain name:**
```caddy
:2015
respond "Hello, world!"
example.com {
root * /var/www/html
file_server
}
```
Then reload the config once again:
Save that to a file named `Caddyfile` (no extension) in the current directory.
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
<aside class="complete">Make a Caddyfile</aside>
Watch the logs to make sure it works:
Stop Caddy if it is already running (Ctrl+C), then run:
<pre><code class="cmd bash">journalctl -u caddy -f</code></pre>
<pre><code class="cmd bash">caddy adapt</code></pre>
- **If it succeeds:** navigate to your site in your browser and see your site served over HTTPS, just like that!
- **If it fails:** refer to the [troubleshooting tips](#troubleshooting) below.
Or if you stored the Caddyfile somewhere else or named it something other than `Caddyfile`:
As you have just seen, Caddy serves sites over HTTPS automatically and by default (unless you explicitly configure `http://` or the HTTP port). As long as you keep your network and DNS properly configured, Caddy will keep your certificates renewed automatically.
<pre><code class="cmd bash">caddy adapt --config /path/to/Caddyfile</code></pre>
Caddy is the only server that works like this!
You will see JSON output! What happened here?
<aside class="complete">Serve your site over HTTPS</aside>
We just used a [_config adapter_](/docs/config-adapters) to convert our Caddyfile to Caddy's native JSON structure.
If you don't want to use a public domain name or are running this internally or locally instead, you can easily have Caddy use [fully-managed self-signed certificates](/docs/automatic-https#local-https) by specifying either:
<aside class="complete">Use the config adapter</aside>
- your local/internal IP address,
- the hostname `localhost`,
- or any hostname that ends in `.localhost`
While we could take that output and make another API request, we can skip all those steps because the `caddy` command can do it for us. If there is a file called Caddyfile in the current directory and no other config is specified, Caddy will load the Caddyfile, adapt it for us, and run it right away.
Now that there is a Caddyfile in the current folder, let's do `caddy run` again:
<pre><code class="cmd bash">caddy run</code></pre>
Or if your Caddyfile is somewhere else:
<pre><code class="cmd bash">caddy run --config /path/to/Caddyfile</code></pre>
(If it is called something else that doesn't start with "Caddyfile", you will need to specify `--adapter caddyfile`.)
You can now try loading your site again and you will see that it is working!
<aside class="complete">Start with an initial config</aside>
As you can see, there are several ways you can start Caddy with an initial config:
- A file named Caddyfile in the current directory
- The `--config` flag (optionally with the `--adapter` flag)
- The `--resume` flag (if a config was loaded previously)
instead of a registered public domain name.
## JSON vs. Caddyfile
## Reverse proxy
Now you know that the Caddyfile is just converted to JSON for you.
Oftentimes, your site consists of a backend application, but you want to put Caddy in front to handle TLS, routing, and other network-related details. Caddy's proxy is easy to use and extremely powerful.
The Caddyfile seems easier than JSON, but should you always use it? There are pros and cons to each approach. The answer depends on your requirements and use case.
For example, if we have a backend that provides the site's API endpoints, we can easily proxy those with just 1 additional line of configuration:
JSON | Caddyfile
-----|----------
Easy to generate | Easy to craft by hand
Easily programmable | Awkward to automate
Extremely expressive | Moderately expressive
Full range of Caddy functionality | Most of Caddy functionality
Allows config traversal | Cannot traverse within Caddyfile
Partial config changes | Whole config changes only
Can be exported | Cannot be exported
Compatible with all API endpoints | Compatible with some API endpoints
Documentation generated automatically | Documentation is hand-written
Ubiquitous | Niche
More efficient | More computational
Kind of boring | Kind of fun
**Learn more: [JSON structure](/docs/json/)** | **Learn more: [Caddyfile docs](/docs/caddyfile)**
```caddy
example.com {
root * /var/www/html
file_server
reverse_proxy /api/* 127.0.0.1:9000
}
```
You will need to decide which is best for your use case.
Notice the `reverse_proxy` directive. The first argument, `/api/*`, is a [path matcher](/docs/caddyfile/matchers) which filters only requests within `/api/`. Then it proxies those to the backend app listening on :9000.
It is important to note that both JSON and the Caddyfile (and [any other supported config adapter](/docs/config-adapters)) can be used with [Caddy's API](/docs/api). However, you get the full range of Caddy's functionality and API features if you use JSON. If using a config adapter, the only way to load or change the config with the API is the [/load endpoint](/docs/api#post-load).
If your backend is a PHP app, simply replace the `reverse_proxy` directive with the `php_fastcgi` directive:
<aside class="complete">Compare JSON and Caddyfile</aside>
```caddy
example.com {
root * /var/www/html
file_server
php_fastcgi /api/* 127.0.0.1:9000
}
```
Make sure the address is the same as your php-fpm listener.
Note that you don't have to enable a file server or set a site root if you _only_ want to proxy requests. You can enable a proxy by itself:
## API vs. Config files
```caddy
example.com {
reverse_proxy 127.0.0.1:9000
}
```
That config terminates TLS and proxies everything to port 9000.
<aside class="complete">Add a reverse proxy</aside>
## Troubleshooting
The most important task when trying to fix a problem is to first get the error message(s) and/or logs.
### Debug logs
Enable debug logging if you haven't already. Put this at the top of your Caddyfile:
```caddy
{
debug
}
```
A block at the very top of the file without any name is called a [global options block](/docs/caddyfile/options). If you already have a global options block, simply add the `debug` option to it; you can't have two global option blocks.
Reload your Caddy configuration and you will observe DEBUG-level logs which can give helpful insights!
### Request logs
Caddy can also log all the HTTP requests it receives (sometimes known as "access logs"). Simply add the `log` directive within your site block. For example:
```caddy
example.com {
root * /var/www/html
file_server
log
}
```
These logs are printed to the same place as Caddy's runtime or process logs (stderr), but have the name `http.log.access` so you can tell them apart. Access logs show you great detail about HTTP requests and responses.
### curl
If your site isn't working the way you expect, avoid using a web browser unless you know what you're doing. Browser behavior is often overly magical, misleading, inconsistent, and frustrating, as it hides or obfuscates the underlying technical details you need to debug your site.
Use `curl -v` instead. The `-v` option prints HTTP information including the header which is vital to knowing what is happening. For example:
<pre><code class="cmd bash">curl -v https://example.com/</code></pre>
<aside class="tip">
Under the hood, even config files go through Caddy's API endpoints; the `caddy` command just wraps up those API calls for you.
To perform the exact same HTTP request as your browser, open its dev tools, go to the Network tab, and right-click the request. There should be an option like "Copy as curl". Then paste that into your terminal.
</aside>
Obviously, change the URL to the one you are trying to debug. You will see curl establish a TLS connection (if HTTPS), make an HTTP request, then print the resulting status code, response headers, and body. It does not follow redirects, enable compression, cache anything, think it is smarter than you, or do anything unexpected. The `curl` command is your true friend and ally in the war against errors.
You will also want to decide whether your workflow is API-based or CLI-based. (You _can_ use both the API and config files on the same server, but we don't recommend it: best to have one source of truth.)
Combined with server logs, curl requests are quite a powerful way to gain insights to what is happening.
API | Config files
----|-------------
Make config changes with HTTP requests | Make config changes with shell commands
Easy to scale | Difficult to scale
Difficult to manage by hand | Easy to manage by hand
Really fun | Also fun
**Learn more: [API tutorial](/docs/api-tutorial)** | **Learn more: [Caddyfile tutorial](/docs/caddyfile-tutorial)**
### Certificates
If Caddy is having trouble getting certificates, leave Caddy running while you double-check your network and DNS configurations. These cause the _vast majority_ of problems.
<aside class="tip">
Manually managing a server's configuration with the API is totally doable with proper tools, for example: any REST client application.
Caddy has special programming for handling certificate automation errors. It will retry with other CAs, gradually back off, and use test CAs (if available) until success. It's usually OK to leave it running while you fix any problems.
</aside>
The choice of API or config file workflow is orthogonal to the use of config adapters: you can use JSON but store it in a file and use the command line interface; conversely, you can also use the Caddyfile with the API.
Check the error messages: Caddy prints the errors as returned by the CA, so they can be quite helpful. For example, a connection timeout indicates the CA couldn't connect to your server, suggesting a problem with your network configuration or DNS records pointing to the wrong network.
But most people will use JSON+API or Caddyfile+CLI combinations.
- Make sure your A/AAAA records are correct.
- Make sure ports 80 and 443 are publicly accessible
- Make sure Caddy&mdash;not another server&mdash;is on the receiving end of ports 80 and 443
As you can see, Caddy is well-suited for a wide variety of use cases and deployments!
### Simplify
<aside class="complete">Compare API and config files</aside>
Many times, configuration files contain more than is needed or relevant to troubleshoot a problem. Try removing everything in your config file except the absolute minimum needed to make the site function. For example, you could disable compression or remove headers added in the reverse proxy. Incrementally making changes to your config will tell you lots about what is causing the problem.
And if nothing undesireable happens or breaks when you remove some config, then you removed config that was unnecessary. Congrats!
If you're behind a CDN like Cloudflare, consider disabling it temporarily while you troubleshoot. If the problem goes away, you can know it is related to your CDN configuration.
## Start, stop, run
<aside class="complete">Learn how to troubleshoot problems</aside>
Since Caddy is a server, it runs indefinitely. That means your terminal won't unblock after you execute `caddy run` until the process is terminated (usually with Ctrl+C).
Although `caddy run` is the most common and is usually recommended (especially when making a system service!), you can alternatively use `caddy start` to start Caddy and have it run in the background:
<pre><code class="cmd bash">caddy start</code></pre>
This will let you use your terminal again, which is convenient in some interactive headless environments.
You will then have to stop the process yourself, since Ctrl+C won't stop it for you:
<pre><code class="cmd bash">caddy stop</code></pre>
Or use [the /stop endpoint](/docs/api#post-stop) of the API.
<aside class="complete">Run in the background</aside>
## Reloading config
Your server can perform zero-downtime config reloads/changes.
All [API endpoints](/docs/api) that load or change config are graceful with zero downtime.
When using the command line, however, it may be tempting to use Ctrl+C to stop your server and then restart it again to pick up the new configuration. Don't do this: stopping and starting the server is orthogonal to config changes, and will result in downtime.
<aside class="tip">
Stopping your server will cause the server to go down.
</aside>
Instead, use the [`caddy reload`](/docs/command-line#caddy-reload) command for a graceful config change:
<pre><code class="cmd bash">caddy reload</code></pre>
This actually just uses the API under the hood. It will load and, if necessary, adapt your config file to JSON, then gracefully replace the active configuration without downtime.
If there are any errors loading the new config, Caddy rolls back to the last working config.
<aside class="tip">
Technically, the new config is started before the old config is stopped, so for a brief time, both configs are running! If the new config fails, it aborts with an error, while the old one is simply not stopped.
</aside>
<aside class="complete">Zero-downtime config reload</aside>

20
src/docs/markdown/install.md
View file

@ -33,17 +33,23 @@ Our [official packages](https://github.com/caddyserver/dist) come only with the
## Static binaries
1. Obtain a Caddy binary:
- [**From releases on GitHub**](https://github.com/caddyserver/caddy/releases) (expand "Assets")
- [**From our download page**](/download)
- [**By building from source**](/docs/build) (either with `go` or `xcaddy`)
2. We recommend [installing Caddy as a system service](/docs/running#manual-installation)
**If installing onto a production system, we recommend using our official package for your distro if available below.**
1. Obtain a Caddy binary:
- [from releases on GitHub](https://github.com/caddyserver/caddy/releases) (expand "Assets")
- [from our download page](/download)
- [by building from source](/docs/build) (either with `go` or `xcaddy`)
2. [Install Caddy as a system service.](/docs/running#manual-installation) This is strongly recommended, especially for production servers.
Place the binary in one of your `$PATH` (or `%PATH%` on Windows) directories so you can run `caddy` without typing the full path of the executable file. (Run `echo $PATH` to see the list of directories that qualify.)
You can upgrade static binaries by replacing them with newer versions and restarting Caddy. The [`caddy upgrade` command](/docs/command-line#caddy-upgrade) can make this easy.
You can upgrade static binaries by replacing them with newer versions and restarting Caddy.
## Debian, Ubuntu, Raspbian
Installing this package automatically starts and runs Caddy as a [systemd service](/docs/running#linux-service) named `caddy`. It also comes with a `caddy-api` service which is _not_ enabled by default but should be used if you primarily configure Caddy via its API instead of config files.
Installing this package automatically starts and runs Caddy as a [systemd service](/docs/running#linux-service) named `caddy`. It also comes with an optional `caddy-api` service which is _not_ enabled by default, but should be used if you primarily configure Caddy via its API instead of config files.
**Stable releases:**

277
src/docs/markdown/introduction.md Normal file
View file

@ -0,0 +1,277 @@
---
title: "Introduction to Caddy"
---
# Introduction
Welcome to Caddy! This tutorial will explore the basics of using Caddy and help you get familiar with it at a high level.
**Objectives:**
- 🔲 Run the daemon
- 🔲 Try the API
- 🔲 Give Caddy a config
- 🔲 Test config
- 🔲 Make a Caddyfile
- 🔲 Use the config adapter
- 🔲 Start with an initial config
- 🔲 Compare JSON and Caddyfile
- 🔲 Compare API and config files
- 🔲 Run in the background
- 🔲 Zero-downtime config reload
**Prerequisites:**
- Basic terminal / command line skills
- Basic text editor skills
- `caddy` and `curl` in your PATH
---
**If you [installed Caddy](/docs/install) from a package manager, Caddy might already be running as a service. If so, please stop the service before doing this tutorial.**
Let's start by running it:
<pre><code class="cmd bash">caddy</code></pre>
Oops; without a subcommand, the `caddy` command only displays help text. You can use this any time you forget what to do.
To start Caddy as a daemon, use the `run` subcommand:
<pre><code class="cmd bash">caddy run</code></pre>
<aside class="complete">Run the daemon</aside>
This blocks forever, but what is it doing? At the moment... nothing. By default, Caddy's configuration ("config") is blank. We can verify this using the [admin API](/docs/api) in another terminal:
<pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
<aside class="tip">
This is **not** your website: the administration endpoint at localhost:2019 is used for controlling Caddy and is restricted to localhost by default.
</aside>
<aside class="complete">Try the API</aside>
We can make Caddy useful by giving it a config. This can be done many ways, but we'll start by making a POST request to the [/load](/docs/api#post-load) endpoint using `curl` in the next section.
## Your first config
To prepare our request, we need to make a config. At its core, Caddy's configuration is simply a [JSON document](/docs/json/).
Save this to a JSON file (e.g. `caddy.json`):
```json
{
"apps": {
"http": {
"servers": {
"example": {
"listen": [":2015"],
"routes": [
{
"handle": [{
"handler": "static_response",
"body": "Hello, world!"
}]
}
]
}
}
}
}
}
```
<aside class="tip">
You do not have to use config files, but we are for this tutorial. Caddy's [admin API](/docs/api) is designed for use by other programs or scripts.
</aside>
Then upload it:
<pre><code class="cmd bash">curl localhost:2019/load \
-H "Content-Type: application/json" \
-d @caddy.json
</code></pre>
<aside class="complete">Give Caddy a config</aside>
We can verify that Caddy applied our new config with another GET request:
<pre><code class="cmd bash">curl localhost:2019/config/</code></pre>
Test that it works by going to [localhost:2015](http://localhost:2015) in your browser or use `curl`:
<pre><code class="cmd"><span class="bash">curl localhost:2015</span>
Hello, world!</code></pre>
If you see _Hello, world!_, then congrats -- it's working! It's always a good idea to make sure your config works as you expect, especially before deploying into production.
<aside class="complete">Test config</aside>
## Your first Caddyfile
That was _kind of a lot of work_ just for Hello World.
Another way to configure Caddy is with the [**Caddyfile**](/docs/caddyfile). The same config we wrote in JSON above can be expressed simply as:
```caddy
:2015
respond "Hello, world!"
```
Save that to a file named `Caddyfile` (no extension) in the current directory.
<aside class="complete">Make a Caddyfile</aside>
Stop Caddy if it is already running (Ctrl+C), then run:
<pre><code class="cmd bash">caddy adapt</code></pre>
Or if you stored the Caddyfile somewhere else or named it something other than `Caddyfile`:
<pre><code class="cmd bash">caddy adapt --config /path/to/Caddyfile</code></pre>
You will see JSON output! What happened here?
We just used a [_config adapter_](/docs/config-adapters) to convert our Caddyfile to Caddy's native JSON structure.
<aside class="complete">Use the config adapter</aside>
While we could take that output and make another API request, we can skip all those steps because the `caddy` command can do it for us. If there is a file called Caddyfile in the current directory and no other config is specified, Caddy will load the Caddyfile, adapt it for us, and run it right away.
Now that there is a Caddyfile in the current folder, let's do `caddy run` again:
<pre><code class="cmd bash">caddy run</code></pre>
Or if your Caddyfile is somewhere else:
<pre><code class="cmd bash">caddy run --config /path/to/Caddyfile</code></pre>
(If it is called something else that doesn't start with "Caddyfile", you will need to specify `--adapter caddyfile`.)
You can now try loading your site again and you will see that it is working!
<aside class="complete">Start with an initial config</aside>
As you can see, there are several ways you can start Caddy with an initial config:
- A file named Caddyfile in the current directory
- The `--config` flag (optionally with the `--adapter` flag)
- The `--resume` flag (if a config was loaded previously)
## JSON vs. Caddyfile
Now you know that the Caddyfile is just converted to JSON for you.
The Caddyfile seems easier than JSON, but should you always use it? There are pros and cons to each approach. The answer depends on your requirements and use case.
JSON | Caddyfile
-----|----------
Easy to generate | Easy to craft by hand
Easily programmable | Awkward to automate
Extremely expressive | Moderately expressive
Full range of Caddy functionality | Most of Caddy functionality
Allows config traversal | Cannot traverse within Caddyfile
Partial config changes | Whole config changes only
Can be exported | Cannot be exported
Compatible with all API endpoints | Compatible with some API endpoints
Documentation generated automatically | Documentation is hand-written
Ubiquitous | Niche
More efficient | More computational
Kind of boring | Kind of fun
**Learn more: [JSON structure](/docs/json/)** | **Learn more: [Caddyfile docs](/docs/caddyfile)**
You will need to decide which is best for your use case.
It is important to note that both JSON and the Caddyfile (and [any other supported config adapter](/docs/config-adapters)) can be used with [Caddy's API](/docs/api). However, you get the full range of Caddy's functionality and API features if you use JSON. If using a config adapter, the only way to load or change the config with the API is the [/load endpoint](/docs/api#post-load).
<aside class="complete">Compare JSON and Caddyfile</aside>
## API vs. Config files
<aside class="tip">
Under the hood, even config files go through Caddy's API endpoints; the `caddy` command just wraps up those API calls for you.
</aside>
You will also want to decide whether your workflow is API-based or CLI-based. (You _can_ use both the API and config files on the same server, but we don't recommend it: best to have one source of truth.)
API | Config files
----|-------------
Make config changes with HTTP requests | Make config changes with shell commands
Easy to scale | Difficult to scale
Difficult to manage by hand | Easy to manage by hand
Really fun | Also fun
**Learn more: [API tutorial](/docs/api-tutorial)** | **Learn more: [Caddyfile tutorial](/docs/caddyfile-tutorial)**
<aside class="tip">
Manually managing a server's configuration with the API is totally doable with proper tools, for example: any REST client application.
</aside>
The choice of API or config file workflow is orthogonal to the use of config adapters: you can use JSON but store it in a file and use the command line interface; conversely, you can also use the Caddyfile with the API.
But most people will use JSON+API or Caddyfile+CLI combinations.
As you can see, Caddy is well-suited for a wide variety of use cases and deployments!
<aside class="complete">Compare API and config files</aside>
## Start, stop, run
Since Caddy is a server, it runs indefinitely. That means your terminal won't unblock after you execute `caddy run` until the process is terminated (usually with Ctrl+C).
Although `caddy run` is the most common and is usually recommended (especially when making a system service!), you can alternatively use `caddy start` to start Caddy and have it run in the background:
<pre><code class="cmd bash">caddy start</code></pre>
This will let you use your terminal again, which is convenient in some interactive headless environments.
You will then have to stop the process yourself, since Ctrl+C won't stop it for you:
<pre><code class="cmd bash">caddy stop</code></pre>
Or use [the /stop endpoint](/docs/api#post-stop) of the API.
<aside class="complete">Run in the background</aside>
## Reloading config
Your server can perform zero-downtime config reloads/changes.
All [API endpoints](/docs/api) that load or change config are graceful with zero downtime.
When using the command line, however, it may be tempting to use Ctrl+C to stop your server and then restart it again to pick up the new configuration. Don't do this: stopping and starting the server is orthogonal to config changes, and will result in downtime.
<aside class="tip">
Stopping your server will cause the server to go down.
</aside>
Instead, use the [`caddy reload`](/docs/command-line#caddy-reload) command for a graceful config change:
<pre><code class="cmd bash">caddy reload</code></pre>
This actually just uses the API under the hood. It will load and, if necessary, adapt your config file to JSON, then gracefully replace the active configuration without downtime.
If there are any errors loading the new config, Caddy rolls back to the last working config.
<aside class="tip">
Technically, the new config is started before the old config is stopped, so for a brief time, both configs are running! If the new config fails, it aborts with an error, while the old one is simply not stopped.
</aside>
<aside class="complete">Zero-downtime config reload</aside>

62
src/docs/markdown/running.md
View file

@ -9,8 +9,8 @@ While Caddy can be run directly with its [command line interface](/docs/command-
- [Linux Service](#linux-service)
- [Unit Files](#unit-files)
- [Using the Service](#using-the-service)
- [Manual Installation](#manual-installation)
- [Using the Service](#using-the-service)
- [Overrides](#overrides)
- [Windows Service](#windows-service)
- [Docker Compose](#docker-compose)
@ -36,35 +36,6 @@ If you need to switch between the services, you should disable and stop the prev
<span class="bash">sudo systemctl enable --now caddy-api</span></code></pre>
### Using the Service
If using a Caddyfile, you can edit your configuration with `nano`, `vi`, or your preferred editor:
<pre><code class="cmd bash">sudo nano /etc/caddy/Caddyfile</code></pre>
You can place your static site files in either `/var/www/html` or `/srv`. Make sure the `caddy` user has permission to read the files.
To verify that the service is running:
<pre><code class="cmd bash">systemctl status caddy</code></pre>
The status command will also show the location of the currently running service file.
When running with our official service file, Caddy's output will be redirected to `journalctl`. To read your full logs and to avoid lines being truncated:
<pre><code class="cmd bash">journalctl -u caddy --no-pager | less +G</code></pre>
If using a config file, you can gracefully reload Caddy after making any changes:
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
You can stop the service with:
<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
<aside class="advice">
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
</aside>
The Caddy process will run as the `caddy` user, which has its `$HOME` set to `/var/lib/caddy`. This means that:
- The default [data storage location](/docs/conventions#data-directory) (for certificates and other state information) will be in `/var/lib/caddy/.local/share/caddy`.
- The default [config storage location](/docs/conventions#configuration-directory) (for the auto-saved JSON config, primarily useful for the `caddy-api` service) will be in `/var/lib/caddy/.config/caddy`.
### Manual Installation
Some [installation methods](/docs/install) automatically set up Caddy to run as a service. If you chose a method that did not, you may follow these instructions to do so:
@ -112,6 +83,37 @@ Verify that it is running:
Now you're ready to [use the service](#using-the-service)!
### Using the Service
If using a Caddyfile, you can edit your configuration with `nano`, `vi`, or your preferred editor:
<pre><code class="cmd bash">sudo nano /etc/caddy/Caddyfile</code></pre>
You can place your static site files in either `/var/www/html` or `/srv`. Make sure the `caddy` user has permission to read the files.
To verify that the service is running:
<pre><code class="cmd bash">systemctl status caddy</code></pre>
The status command will also show the location of the currently running service file.
When running with our official service file, Caddy's output will be redirected to `journalctl`. To read your full logs and to avoid lines being truncated:
<pre><code class="cmd bash">journalctl -u caddy --no-pager | less +G</code></pre>
If using a config file, you can gracefully reload Caddy after making any changes:
<pre><code class="cmd bash">sudo systemctl reload caddy</code></pre>
You can stop the service with:
<pre><code class="cmd bash">sudo systemctl stop caddy</code></pre>
<aside class="advice">
Do not stop the service to change Caddy's configuration. Stopping the server will incur downtime. Use the reload command instead.
</aside>
The Caddy process will run as the `caddy` user, which has its `$HOME` set to `/var/lib/caddy`. This means that:
- The default [data storage location](/docs/conventions#data-directory) (for certificates and other state information) will be in `/var/lib/caddy/.local/share/caddy`.
- The default [config storage location](/docs/conventions#configuration-directory) (for the auto-saved JSON config, primarily useful for the `caddy-api` service) will be in `/var/lib/caddy/.config/caddy`.
### Overrides
The best way to override aspects of the service files is with this command:

1
src/includes/docs/nav.html
View file

@ -9,6 +9,7 @@
<li class="heading">Tutorials</li>
<li><a href="/docs/getting-started">Getting Started</a></li>
<li><a href="/docs/introduction">Introduction</a></li>
<li>
<a href="/docs/quick-starts">Quick-starts</a>
<ul>