From 927e250f41b9a3c43cb98ab50191e310f864684f Mon Sep 17 00:00:00 2001
From: polarathene <5098581+polarathene@users.noreply.github.com>
Date: Wed, 5 Aug 2020 20:31:04 +1200
Subject: [PATCH] docs: Better clarify the `auto_https` options and Caddyfile
config
---
src/docs/markdown/automatic-https.md | 84 ++++++++++++++++++++++++-
src/docs/markdown/caddyfile/options.md | 2 +-
src/docs/markdown/quick-starts/https.md | 4 +-
3 files changed, 87 insertions(+), 3 deletions(-)
diff --git a/src/docs/markdown/automatic-https.md b/src/docs/markdown/automatic-https.md
index 3decfca..1ceb6b0 100644
--- a/src/docs/markdown/automatic-https.md
+++ b/src/docs/markdown/automatic-https.md
@@ -23,7 +23,7 @@ Here's a 28-second video showing how it works:
- 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.
+Caddy keeps all certificates renewed, and redirects HTTP (default port 80) to HTTPS (default port 443) automatically (provided [Activation](/docs/automatic-https#activation) is successful).
**For local HTTPS:**
@@ -76,6 +76,8 @@ Automatic HTTPS never overrides explicit configuration.
You can [customize or disable automatic HTTPS](/docs/json/apps/http/servers/automatic_https/) if necessary.
+
+
## Hostname requirements
@@ -220,3 +222,83 @@ Before attempting any ACME transactions, Caddy will test the configured storage
Caddy can obtain and manage wildcard certificates when it is configured to serve a site with a qualifying wildcard name. A site name qualifies for a wildcard if only its left-most domain label is a wildcard. For example, `*.example.com` qualifies, but these do not: `sub.*.example.com`, `foo*.example.com`, `*bar.example.com`, and `*.*.example.com`.
To get a wildcard from Let's Encrypt, you simply need to enable the [DNS challenge](#dns-challenge) and use a wildcard domain in your config. We recommend using wildcards only when you have so many subdomains that you would encounter CA rate limits trying to obtain certificates for them all.
+
+
+
+## Examples
+
+Caddy implicitly uses the HTTPS port (default 443) for your [server addresses](/docs/conventions#network-addresses) that don't assign an explicit port (which would disable automatic HTTPS).
+
+The global setting `auto_https` has two values:
+- `disable_redirects` adds an implicit HTTP port redirect.
+- `off` disables automatic HTTPS, default implicit port changes to HTTP for all server addresses.
+
+| auto_https | HTTP | HTTPS |
+|-------------------|-------------|-------------|
+| *default* | redirects | connects |
+| disable_redirects | unreachable | connects |
+| off | connects | unreachable |
+
+`unreachable` is the default without additional configuration when using the related `auto_https` setting.
+`connects` is the implicitly assigned port.
+
+
+### Disabling automatic HTTPS
+
+For local development environments, you can prevent serving via HTTPS by providing an explicit port assignment(disable per server address) or using the global `auto_https off` setting which will change Caddy's implicit port to be the HTTP port (default 80) globally.
+
+```caddy
+{
+ auto_https off
+}
+
+# Have caddy implicitly use the HTTP port
+localhost {
+ root * /usr/share/caddy
+
+ file_server
+}
+```
+
+```caddy
+# Alternatively, provide an explicit port
+localhost:9000 {
+ root * /usr/share/caddy
+
+ file_server
+}
+```
+
+
+### HTTP and HTTPS without redirect
+
+If you want to serve content through both HTTP and HTTPS ports without HTTP redirects, your server address cannot rely on a single implicit port and you must explicitly declare the intent to listen from both ports.
+
+To do so, you can [map several addresses to a site block as a list](/docs/caddyfile/concepts#addresses) separated with `,`:
+
+```caddy
+{
+ auto_https disable_redirects
+}
+
+# Uses the HTTP and HTTPS by protocol
+# These are configurable as global settings
+http://localhost, https://localhost {
+ root * /usr/share/caddy
+
+ file_server
+}
+```
+
+```caddy
+{
+ auto_https disable_redirects
+}
+
+# Alternatively provide explicit ports
+localhost:80, localhost:443 {
+ root * /usr/share/caddy
+
+ file_server
+}
+```
diff --git a/src/docs/markdown/caddyfile/options.md b/src/docs/markdown/caddyfile/options.md
index a74b6f9..947a554 100644
--- a/src/docs/markdown/caddyfile/options.md
+++ b/src/docs/markdown/caddyfile/options.md
@@ -60,4 +60,4 @@ Possible options are:
- **interval** and **burst** allows `` certificate operations within `` 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.
- **key_type** specifies the type of key to generate for TLS certificates; only change this if you have a specific need to customize it.
-- **auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`).
+- **auto_https** configure automatic HTTPS. It can either disable it entirely (`off`) or disable only HTTP-to-HTTPS redirects (`disable_redirects`). [Examples](/docs/automatic-https#examples).
diff --git a/src/docs/markdown/quick-starts/https.md b/src/docs/markdown/quick-starts/https.md
index 7b33d4e..24324c8 100644
--- a/src/docs/markdown/quick-starts/https.md
+++ b/src/docs/markdown/quick-starts/https.md
@@ -7,7 +7,9 @@ title: HTTPS quick-start
This guide will show you how to get up and running with [fully-managed HTTPS](/docs/automatic-https) in no time.
**Prerequisites:**