diff --git a/src/docs/markdown/automatic-https.md b/src/docs/markdown/automatic-https.md index 971220d..0ce416c 100644 --- a/src/docs/markdown/automatic-https.md +++ b/src/docs/markdown/automatic-https.md @@ -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/). diff --git a/src/docs/markdown/caddyfile/concepts.md b/src/docs/markdown/caddyfile/concepts.md index 1945ad1..84a5511 100644 --- a/src/docs/markdown/caddyfile/concepts.md +++ b/src/docs/markdown/caddyfile/concepts.md @@ -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 \` \` 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 ` 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: diff --git a/src/docs/markdown/caddyfile/directives.md b/src/docs/markdown/caddyfile/directives.md index 9e624fc..02f14fb 100644 --- a/src/docs/markdown/caddyfile/directives.md +++ b/src/docs/markdown/caddyfile/directives.md @@ -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:
diff --git a/src/docs/markdown/install.md b/src/docs/markdown/install.md index 5335ccf..8753ef5 100644 --- a/src/docs/markdown/install.md +++ b/src/docs/markdown/install.md @@ -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:** diff --git a/src/docs/markdown/running.md b/src/docs/markdown/running.md index e3e8037..b809752 100644 --- a/src/docs/markdown/running.md +++ b/src/docs/markdown/running.md @@ -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 sudo systemctl enable --now caddy-api -### Using the Service - -If using a Caddyfile, you can edit your configuration with `nano`, `vi`, or your preferred editor: -
sudo nano /etc/caddy/Caddyfile
- -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: -
systemctl status caddy
-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: -
journalctl -u caddy --no-pager | less +G
- -If using a config file, you can gracefully reload Caddy after making any changes: -
sudo systemctl reload caddy
- -You can stop the service with: -
sudo systemctl stop caddy
- - - -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: +
sudo nano /etc/caddy/Caddyfile
+ +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: +
systemctl status caddy
+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: +
journalctl -u caddy --no-pager | less +G
+ +If using a config file, you can gracefully reload Caddy after making any changes: +
sudo systemctl reload caddy
+ +You can stop the service with: +
sudo systemctl stop caddy
+ + + +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: