From d3a35d67e88165143c20b3878cb1ae97efd51f64 Mon Sep 17 00:00:00 2001
From: Matthew Holt <mholt@users.noreply.github.com>
Date: Wed, 8 Apr 2020 13:34:18 -0600
Subject: [PATCH] docs: Add tips for permissions errors in tutorials; explain
 durability

---
 src/docs/markdown/api.md                    | 2 +-
 src/docs/markdown/caddyfile-tutorial.md     | 8 ++++++++
 src/docs/markdown/quick-starts/caddyfile.md | 5 +++++
 3 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/docs/markdown/api.md b/src/docs/markdown/api.md
index ce7791d..f66362a 100644
--- a/src/docs/markdown/api.md
+++ b/src/docs/markdown/api.md
@@ -8,7 +8,7 @@ Caddy is configured through an administration endpoint which can be accessed via
 
 **Default address: `localhost:2019`**
 
-The latest configuration will be saved to disk after any changes (unless [disabled](/docs/json/admin/config/)). You can resume the last working config after a restart with [`caddy run --resume`](/docs/command-line#caddy-run).
+The latest configuration will be saved to disk after any changes (unless [disabled](/docs/json/admin/config/)). You can resume the last working config after a restart with [`caddy run --resume`](/docs/command-line#caddy-run), which guarantees config durability in the event of a power cycle or similar.
 
 To get started with the API, try our [API tutorial](/docs/api-tutorial) or, if you only have a minute, our [API quick-start guide](/docs/quick-starts/api).
 
diff --git a/src/docs/markdown/caddyfile-tutorial.md b/src/docs/markdown/caddyfile-tutorial.md
index bfcec30..56afb70 100644
--- a/src/docs/markdown/caddyfile-tutorial.md
+++ b/src/docs/markdown/caddyfile-tutorial.md
@@ -31,6 +31,10 @@ The first thing you should type is your site's [address](/docs/caddyfile/concept
 localhost
 ```
 
+<aside class="tip">
+	If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like <code>localhost:2015</code>. You'll still get HTTPS unless you turn it off.
+</aside>
+
 Then hit enter and type what you want it to do. For this tutorial, make your Caddyfile look like this:
 
 ```
@@ -43,6 +47,10 @@ Save that and run Caddy (since this is a training tutorial, we'll use the `--wat
 
 <pre><code class="cmd bash">caddy run --watch</code></pre>
 
+<aside class="tip">
+	If you get permissions errors, try using a higher port in your address, like <code>localhost:2015</code> for example, or run with elevated privileges.
+</aside>
+
 The first time, you'll be asked for your password. This is so Caddy can serve your site over HTTPS.
 
 <aside class="tip">Caddy serves all sites over HTTPS by default as long as a host or IP is part of the site's address. <a href="/docs/automatic-https">Automatic HTTPS</a> can be disabled by prefixing the address with <code>http://</code> explicitly.</aside>
diff --git a/src/docs/markdown/quick-starts/caddyfile.md b/src/docs/markdown/quick-starts/caddyfile.md
index c087b55..a135c64 100644
--- a/src/docs/markdown/quick-starts/caddyfile.md
+++ b/src/docs/markdown/quick-starts/caddyfile.md
@@ -12,6 +12,10 @@ The first thing to type in a Caddyfile is your site's address:
 localhost
 ```
 
+<aside class="tip">
+	If the HTTP and HTTPS ports (80 and 443, respectively) are privileged ports on your OS, you will either need to run with elevated privileges or use a higher port. To use a higher port, just change the address to something like <code>localhost:2015</code>. You'll still get HTTPS unless you turn it off.
+</aside>
+
 Then hit enter and type what you want it to do, so it looks like this:
 
 ```
@@ -30,6 +34,7 @@ You will probably be asked for your password, because Caddy serves all sites --
 	For local HTTPS, Caddy automatically generates certificates and unique private keys for you. The root certificate is added to your system's trust store, which is why the password prompt is necessary. It allows you to develop locally over HTTPS without certificate errors.
 </aside>
 
+If you get permission errors, you may need to run with elevated privileges or use a higher port; a quick fix is to change your site's address to `localhost:2015` or similar.
 
 Either open your browser to [localhost](http://localhost) or `curl` it: