docs: General updates for beta 18

src/docs/markdown/automatic-https.md

@@ -20,7 +20,7 @@ Here's a 28-second video showing how it works:
 
 **Caddy serves all sites over HTTPS by default.**
 
-- Caddy serves IP addresses and local/internal hostnames over HTTPS with locally-trusted ceritficates. Examples: `localhost`, `127.0.0.1`.
+- Caddy serves IP addresses and local/internal hostnames over HTTPS with locally-trusted certificates. Examples: `localhost`, `127.0.0.1`.
 - Caddy serves public DNS names over HTTPS with certificates from [Let's Encrypt](https://letsencrypt.org). Examples: `example.com`, `sub.example.com`, `*.example.com`.
 
 Caddy keeps all certificates renewed, and redirects HTTP (default port 80) to HTTPS (default port 443) automatically.
@@ -174,15 +174,15 @@ If the DNS challenge is enabled, other challenges are disabled by default.
 
 ## On-Demand TLS
 
-Caddy pioneers a new technology we call On-Demand TLS, which obtains the certificate for a name during the first TLS handshake that requires it, rather than at config load. You can enable it using the [on_demand](/docs/json/apps/tls/automation/on_demand/) property in your TLS automation config.
+Caddy pioneered a new technology we call On-Demand TLS, which obtains the certificate for a name during the first TLS handshake that requires it, rather than at config load. You can enable it using the [on_demand](/docs/json/apps/tls/automation/on_demand/) property in your TLS automation config, or the [on_demand Caddyfile subdirective](/docs/caddyfile/directives/tls#syntax).
 
-This feature can be useful if you do not know all the domain names up front. Certificates managed on-demand will be obtained and renewed in the foreground of TLS handshakes that require it. This process slows down only the initial TLS handshake; all others will not be affected.
+This feature can be useful if you do not know all the domain names up front, or if domain names you know of may not be properly configured right away (e.g. DNS records not yet set correctly). Certificates managed on-demand will be obtained and renewed in the foreground of TLS handshakes that require it. This process slows down only the initial TLS handshake; all others will not be affected.
 
 To prevent abuse, you should specify rate limits and/or an endpoint that Caddy can query to ask if a certificate is allowed to be obtained for a hostname. Essentially, you still need a way to provide a whitelist, but this can be managed dynamically using your own scripts or programs if you'd rather keep Caddy's config more static.
 
 **Future support:** This feature relies on the CA issuing certificates without delay. If instantaneous issuance becomes uncommon among ACME CAs, we may discontinue this feature in Caddy.
 
-Due to its deferred nature and the possibility that some ACME challenges can take more than a few seconds (especially when using the DNS challenge), we typically recommend using On-Demand TLS only when there are specific technical or operational advantages to you.
+Due to its deferred nature and the possibility that some ACME challenges can take more than a few seconds (especially when using the DNS challenge), we typically recommend using On-Demand TLS only when there are specific technical or operational advantages to you; namely, if the DNS records for a domain are not in your control, and you do not know when they will be properly set and ready to get certificates.
 
 
 ## Errors

src/docs/markdown/caddyfile/directives.md

@@ -23,12 +23,10 @@ Directive | Description
 **[rewrite](/docs/caddyfile/directives/rewrite)** | Rewrites the request internally
 **[root](/docs/caddyfile/directives/root)** | Set the path to the site root
 **[route](/docs/caddyfile/directives/route)** | A group of directives treated literally as single unit
-**[strip_prefix](/docs/caddyfile/directives/strip_prefix)** | Rewrite that strips path prefix
-**[strip_suffix](/docs/caddyfile/directives/strip_suffix)** | Rewrite that strips path suffix
 **[templates](/docs/caddyfile/directives/templates)** | Execute templates on the response
 **[tls](/docs/caddyfile/directives/tls)** | Customize TLS settings
 **[try_files](/docs/caddyfile/directives/try_files)** | Rewrite that depends on file existence
-**[uri_replace](/docs/caddyfile/directives/uri_replace)** | Rewrite that replaces substrings in URI
+**[uri](/docs/caddyfile/directives/uri)** | Manipulate the URI
 
 
 ## Syntax
@@ -73,9 +71,7 @@ root
 redir
 rewrite
 
-strip_prefix
+uri
-strip_suffix
-uri_replace
 try_files
 
 basicauth
@@ -93,4 +89,4 @@ php_fastcgi
 file_server
 ```
 
-You can override or customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).
+You can override/customize this ordering by using the [`order` global option](/docs/caddyfile/options) or the [`route` directive](/docs/caddyfile/directives/route).

src/docs/markdown/caddyfile/directives/rewrite.md

@@ -8,6 +8,8 @@ Rewrites the request internally. A rewrite changes some or all of the request UR
 
 The `rewrite` directive implies the intent to accept the request, but with modifications. It is mutually exclusive to other `rewrite` directives in the same block, so it is safe to define rewrites that would otherwise cascade into each other; only the first matching rewrite will be executed.
 
+Because `rewrite` essentially performs an internal redirect, the Caddyfile adapter will not fold any subsequent, adjacent handlers into the same route if their matchers happen to be exactly the same. This allows the matchers of the next handlers to be deferred until after the rewrite. In other words, a matcher that matches a request before the `rewrite` might not match the same request after the `rewrite`. If you want your `rewrite` to share a route with other handlers, use the [`route`](route) or [`handle`](handle) directives.
+
 
 ## Syntax
 
@@ -49,7 +51,5 @@ rewrite * /index.php?{query}&p={path}
 
 There are other directives that perform rewrites, but imply a different intent or do the rewrite without a complete replacement of the URI:
 
-- [`strip_prefix`](/docs/caddyfile/directives/strip_prefix) strips a prefix from the request path.
+- [`uri`](uri) manipulates a URI (strip prefix, suffix, or substring replacement).
-- [`strip_suffix`](/docs/caddyfile/directives/strip_suffix) strips a suffix from the request path.
+- [`try_files`](try_files) rewrites the request based on the existence of files.
-- [`uri_replace`](/docs/caddyfile/directives/uri_replace) performs a substring replacement on the request path.
-- [`try_files`](/docs/caddyfile/directives/try_files) rewrites the request based on the existence of files.

src/docs/markdown/caddyfile/directives/route.md

@@ -70,7 +70,7 @@ Strip `api/` prefix from request path just before proxying all API requests to a
 
 ```
 route /api/* {
-	strip_prefix  api/
+	uri strip_prefix api/
 	reverse_proxy localhost:9000
 }
 ```

src/docs/markdown/caddyfile/directives/strip_prefix.md

@@ -1,31 +0,0 @@
----
-title: strip_prefix (Caddyfile directive)
----
-
-# strip_prefix
-
-Strips a given prefix from the request URI's path. If a matched request does not have the given path prefix, this directive is a no-op.
-
-
-## Syntax
-
-```
-strip_prefix [<matcher>] <prefix>
-```
-
-- **&lt;prefix&gt;** is the prefix to strip from the request path. This value may omit the leading forward slash `/` and it will be assumed.
-
-
-## Examples
-
-Strip `api/` from the beginning of all request paths:
-
-```
-strip_prefix api/
-```
-
-An alternate way to describe the same thing, using a matcher:
-
-```
-strip_prefix /api/* /api
-```

src/docs/markdown/caddyfile/directives/strip_suffix.md

@@ -1,25 +0,0 @@
----
-title: strip_suffix (Caddyfile directive)
----
-
-# strip_suffix
-
-Strips a given suffix from the request URI's path. If a matched request does not have the given path suffix, this directive is a no-op.
-
-
-## Syntax
-
-```
-strip_suffix [<matcher>] <suffix>
-```
-
-- **&lt;suffix&gt;** is the suffix to strip from the request path.
-
-
-## Examples
-
-Strip `.html` from the end of all request paths:
-
-```
-strip_suffix .html
-```

src/docs/markdown/caddyfile/directives/tls.md

@@ -22,6 +22,7 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 	load      <paths...>
 	ca        <ca_dir_url>
 	ca_root   <pem_file>
+	on_demand
 }
 ```
 
@@ -58,20 +59,34 @@ tls [internal|<email>] | [<cert_file> <key_file>] {
 - **load** specifies a list of folders from which to load PEM files that are certificate+key bundles.
 - **ca** changes the ACME CA endpoint. This is most often used to use [Let's Encrypt's staging endpoint](https://letsencrypt.org/docs/staging-environment/) or an internal ACME server. (To change this value for the whole Caddyfile, use the `acme_ca` [global option](/docs/caddyfile/options) instead.)
 - **ca_root** specifies a PEM file that contains a trusted root certificate for the ACME CA endpoint, if not in the system trust store.
+- **on_demand** enables [on-demand TLS](/docs/automatic-https#on-demand-tls) for the hostnames given in the site block's address(es).
 
 
 
 ## Examples
 
-Specify an email address for your ACME account:
-
-```
-tls your@email.com
-```
-
 Use a custom certificate and key:
 
 ```
 tls cert.pem key.pem
 ```
 
+Use locally-trusted certificates for all hosts on the current site block, rather than public certificates via ACME / Let's Encrypt (useful in dev environments):
+
+```
+tls internal
+```
+
+Use locally-trusted certificates, but managed on-demand intead of in the background:
+
+```
+tls internal {
+	on_demand
+}
+```
+
+Specify an email address for your ACME account (but if only one email is used for all sites, we recommend the `email` [global option](/docs/caddyfile/options) instead):
+
+```
+tls your@email.com
+```

src/docs/markdown/caddyfile/directives/uri.md

@@ -0,0 +1,47 @@
+---
+title: uri (Caddyfile directive)
+---
+
+# uri
+
+Manipulates a request's URI. It can strip path prefix/suffix or replace substrings on the whole URI.
+
+This directive is distinct from [`rewrite`](rewrite) in that `uri` _partially_ changes the URI, rather than setting it to something completely different as `rewrite` does. While `rewrite` is treated specially as an internal redirect, `uri` is just another handler.
+
+
+## Syntax
+
+```
+uri [<matcher>] strip_prefix|strip_suffix|replace \
+	<target> \
+	[<replacement> [<limit>]]
+```
+
+- The first (non-matcher) argument specifies the operation:
+	- **strip_prefix** strips a prefix from the path, if it has the prefix.
+	- **strip_suffix** strips a suffix from the path, if it has the suffix.
+	- **replace** performs a substring replacement across the whole URI.
+- **&lt;target&gt;** is the prefix, suffix, or search string/regular expression. If a prefix, the leading forward slash may be omitted, since paths always start with a forward slash.
+- **&lt;replacement&gt;** is the replacement string (only valid with `replace`).
+- **&lt;limit&gt;** is an optional limit to the maximum number of replacements (only valid with `replace`).
+
+
+## Examples
+
+Strip `api/` from the beginning of all request paths:
+
+```
+uri strip_prefix api/
+```
+
+Strip `.php` from the end of all request paths:
+
+```
+uri strip_suffix .php
+```
+
+Replace "/docs/" with "/v1/docs/" in any request URI:
+
+```
+uri replace /docs/ /v1/docs/
+```

src/docs/markdown/caddyfile/directives/uri_replace.md

@@ -1,27 +0,0 @@
----
-title: uri_replace (Caddyfile directive)
----
-
-# uri_replace
-
-Performs a substring or regular expression replacement in the request URI.
-
-
-## Syntax
-
-```
-uri_replace [<matcher>] <find> <replace> [<limit>]
-```
-
-- **&lt;find&gt;** is the substring or regular expression to search for.
-- **&lt;replace&gt;** is the replacement value.
-- **&lt;limit&gt;** is an optional limit to the number of replacements.
-
-
-## Examples
-
-Replace "/docs/" with "/v1/docs/" in any request URI:
-
-```
-uri_replace * /docs/ /v1/docs/
-```

src/docs/markdown/caddyfile/options.md

@@ -20,30 +20,40 @@ Possible options are:
 
 ```
 {
+	debug
 	http_port   <port>
 	https_port  <port>
+	default_sni <name>
 	order <dir1> first|last|[before|after <dir2>]
+	experimental_http3
 	storage <module_name> {
 		<options...>
 	}
-	experimental_http3
-	default_sni <name>
 	acme_ca <directory_url>
 	acme_ca_root <pem_file>
 	email   <yours>
 	admin   off|<addr>
-	debug
+	on_demand_tls {
+		ask      <endpoint>
+		interval <duration>
+		burst    <n>
+	}
+	local_certs
 }
 ```
 
+- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).
 - **http_port** is the port for the server to use for HTTP. For internal use only; does not change the HTTP port for clients. Default: 80
 - **https_port** is the port for the server to use for HTTPS. For internal use only; does not change the HTTPS port for clients. Default: 443
-- **order** sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive.
-- **storage** configures Caddy's storage mechanism. Default: `file_system`
 - **default_sni** sets a default TLS ServerName for when clients do not use SNI in their ClientHello.
+- **order** sets or changes the standard order of HTTP handler directive(s). Can set directives to be `first` or `last`, or `before` or `after` another directive.
 - **experimental_http3** enables experimental draft HTTP/3 support. Note that HTTP/3 is not a finished spec and client support is extremely limited. This option will go away in the future. _This option is not subject to compatibility promises._
+- **storage** configures Caddy's storage mechanism. Default: `file_system`
 - **acme_ca** specifies the URL to the ACME CA's directory. It is strongly recommended to set this to Let's Encrypt's [staging endpoint](https://letsencrypt.org/docs/staging-environment/) for testing or development. Default: Let's Encrypt's production endpoint.
 - **acme_ca_root** specifies a PEM file that contains a trusted root certificate for ACME CA endpoints, if not in the system trust store.
 - **email** is your email address. Mainly used when creating an ACME account with your CA, and is highly recommended in case there are problems with your certificates.
 - **admin** customizes the [admin API endpoint](/docs/api). If `off`, then the admin endpoint will be disabled.
-- **debug** enables debug mode, which sets all log levels to debug (unless otherwise specified).
+- **on_demand_tls** configures [On-Demand TLS](/docs/automatic-https#on-demand-tls) where it is enabled, but does not enable it (to enable it, use the [on_demand `tls` subdirective](/docs/caddyfile/directives/tls#syntax)). Highly recommended if using in production environments, to prevent abuse.
+	- **ask** will cause Caddy to make an HTTP request to the given URL with a query string of `?domain=` containing the value of the domain name. If the endpoint returns 200 OK, Caddy will be authorized to obtain a certificate for that name.
+	- **interval** and **burst** allows `<n>` certificate operations within `<duration>` interval.
+- **local_certs** causes all certificates to be issued internally by default, rather than through a (public) ACME CA such as Let's Encrypt. This is useful in development environments.

src/docs/markdown/command-line.md

@@ -132,7 +132,8 @@ Prints the environment as seen by caddy, then exits. Can be useful when debuggin
 	[--root <path>]
 	[--listen <addr>]
 	[--domain <example.com>]
-	[--browse]</code></pre>
+	[--browse]
+	[--templates]</code></pre>
 
 Spins up a simple but production-ready static file server.
 
@@ -144,6 +145,8 @@ Spins up a simple but production-ready static file server.
 
 `--browse` will enable directory listings if a directory without an index file is requested.
 
+`--templates` will enable template rendering.
+
 This command disables the admin API, making it easier to run multiple instances on a local development machine.
 
 
@@ -152,13 +155,13 @@ This command disables the admin API, making it easier to run multiple instances
 ### `caddy fmt`
 
 <pre><code class="cmd bash">caddy fmt [&lt;path&gt;]
-	[--write]</code></pre>
+	[--overwrite]</code></pre>
 
-Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--write` is used.
+Formats or prettifies a Caddyfile, then exits. The result is printed to stdout unless `--overwrite` is used.
 
 `<path>` specifies the path to the Caddyfile. If omitted, a file named Caddyfile in the current directory is assumed instead.
 
-`--write` causes the result to be written to the input file instead of being printed to the terminal.
+`--overwrite` causes the result to be written to the input file instead of being printed to the terminal.
 
 
 
@@ -207,7 +210,7 @@ NOTE: Due to [a bug in Go](https://github.com/golang/go/issues/29228), version i
 	[--adapter &lt;name&gt;]
 	[--address &lt;interface&gt;]</code></pre>
 
-Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the [/load endpoint](/docs/api#post-load), but this command is convenient for simple workflows revolving around config files.
+Gives the running Caddy instance a new configuration. This has the same effect as POSTing a document to the [/load endpoint](/docs/api#post-load), but this command is convenient for simple workflows revolving around config files. Compared to the `stop`, `start`, and `run` commands, this single command is the correct, semantic way to change/reload the running configuration.
 
 `--config` is the config file to apply. If not specified, it will try a file called `Caddyfile` in the current working directory and, if it exists, it will adapt it using the `caddyfile` config adapter; otherwise, it is an error if there is no config file to load.
 
@@ -245,6 +248,10 @@ This command disables the admin API, making it easier to run multiple instances
 	[--environ]
 	[--resume]</code></pre>
 
+<aside class="tip">
+	To change the active configuration while running in production, do not stop the server! That will result in downtime. (This should be obvious but you'd be surprised how many complaints we get about it.) Use the <a href="#caddy-reload">caddy reload</a> command instead.
+</aside>
+
 Runs Caddy and blocks indefinitely; i.e. "daemon" mode.
 
 `--config` specifies an initial config file to immediately load and use. If no config is specified, Caddy will run with a blank configuration and use default settings for the [admin API endpoints](/docs/api), which can be used to feed it new configuration. As a special case, if the current working directory has a file called "Caddyfile" and the `caddyfile` config adapter is plugged in (default), then that file will be loaded and used to configure Caddy, even without any command line flags.
@@ -274,6 +281,10 @@ Once started, you can use [`caddy stop`](#caddy-stop) or [the /stop API endpoint
 
 <pre><code class="cmd bash">caddy stop [--address &lt;interface&gt;]</code></pre>
 
+<aside class="tip">
+	Stopping (and restarting) the server is orthogonal to config changes. Do not use the stop command to change configuration in production, unless you want downtime. Use the <a href="#caddy-reload">caddy reload</a> command instead.
+</aside>
+
 Gracefully stops the running Caddy process (other than the process of the stop command) and causes it to exit. It uses the [/stop endpoint](/docs/api#post-stop) of the admin API to perform a graceful shutdown.
 
 `--address` can be used if the running instance's admin API is not on the default port; an alternate address can be specified here.