mirror of https://github.com/caddyserver/website.git synced 2025-04-22 13:06:16 -04:00

docs: Some cleanup, some v2.4.0 additions (#139 )

* docs: Some cleanup, some v2.4.0 additions

- Add `abort` directive docs
- Add a note in `handle` to cross-link to `handle_path`
- Add another example in `handle_errors` that shows how an `expression` matcher can be used to pair with it
- Add a cat emoji to handle_errors because 😸
- Add `file_server` to one of the `php_fastcgi` examples, it's rare that you'll ever use it without `file_server` so might as well include it there
- Add a TOC to `reverse_proxy` cause it's such a long page. Maybe we'll add one to other pages as well, but TBD
- Clarify the upstream address stuff a bit after some discussion in https://caddy.community/t/reverse-proxy-with-multiple-different-upstreams-with-paths/11512/12 and mention `rewrite` as the alternative
- Use the `{re.*.*}` shortcut in the Caddyfile matcher docs, links to the placeholder mapping to let people trace where that comes from

* docs: Revise the `handle` cross-linking, add another example

* docs: Bump minimum Go version to 1.15

* docs: A bunch more additions since v2.3.0

I went through the whole list of commits here: https://github.com/caddyserver/caddy/compare/v2.3.0...ec3ac84

* docs: Review feedback

* docs: Link to https://golang.org/doc/install, better instructions

2021-02-22 13:11:21 -07:00

2.1 KiB

Raw Blame History

title
handle (Caddyfile directive)

handle

Evaluates a group of directives mutually exclusively from other handle blocks at the same level of nesting.

The handle directive is kind of similar to the location directive from nginx config: the first matching handle block will be evaluated. Handle blocks can be nested if needed. Only HTTP handler directives can be used inside handle blocks.

Syntax

handle [<matcher>] {
	<directives...>
}

<directives...> is a list of HTTP handler directives or directive blocks, one per line, just like would be used outside of a handle block.

Utility

If you prefer crafting HTTP handler logic in a more inheritence-based way like nginx location blocks, you may prefer the use of handle blocks rather than defining mutually-exclusive matchers for your directives. If inheritence is a desired characteristic of your HTTP handler configurations, then the handle directive may suit you well.

Similar directives

There are other directives that can wrap HTTP handler directives, but each has its use depending on the behavior you want to convey:

handle_path does the same as handle, but it strips a prefix from the request before running its handlers.
handle_errors is like handle, but is only invoked when Caddy encounters an error during request handling.
route wraps other directives like handle does, but with two distinctions: 1) route blocks are not mutually exclusive to each other, and 2) directives within a route are not [re-ordered](directive order, giving you more control if needed.

Examples

Handle requests in /foo/ by the static file server, and send all other requests to the reverse proxy:

handle /foo/* {
	file_server
}
handle {
	reverse_proxy 127.0.0.1:8080
}

You can mix handle and handle_path directives in the same site, and they will still be mutually exclusive from each other:

handle_path /foo/* {
	# The path has the "/foo" prefix stripped
}

handle /bar/* {
	# The path still retains "/bar"
}

2.1 KiB Raw Blame History