From 21431156283806f9145b424386cbf9b2133301ce Mon Sep 17 00:00:00 2001
From: AJ ONeal <aj@therootcompany.com>
Date: Thu, 8 Oct 2020 19:57:11 +0000
Subject: [PATCH] update caddy cheat sheet

---
 caddy/README.md | 131 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 131 insertions(+)

diff --git a/caddy/README.md b/caddy/README.md
index 93324c2..020ded8 100644
--- a/caddy/README.md
+++ b/caddy/README.md
@@ -19,6 +19,15 @@ Use the `@beta` tag for pre-releases, or `@x.y.z` for a specific version.
 > reverse proxy APIs and WebSockets to other apps - such as those written node,
 > Go, python, ruby, and PHP.
 
+Here's the things we find most useful:
+
+- Simple File & Directory Server
+- Reverse Proxy with www (and HTTPS) redirects
+- Running as a system service on
+  - Linux
+  - MacOS
+  - Windows 10
+
 ### How to serve a directory
 
 ```bash
@@ -48,12 +57,18 @@ example.com {
     # reverse proxy /api to :3000
     reverse_proxy /api/* localhost:3000
 
+    # reverse proxy some "well known" APIs
+    reverse_proxy /.well-known/openid-configuration localhost:3000
+    reverse_proxy /.well-known/jwks.json localhost:3000
+
     # serve static files from public folder, but not /api
     @notApi {
         file {
             try_files {path} {path}/ {path}/index.html
         }
         not path /api/*
+        not path /.well-known/openid-configuration
+        not path /.well-known/jwks.json
     }
     route {
       rewrite @notApi {http.matchers.file.relative}
@@ -68,3 +83,119 @@ And here's how you run caddy with it:
 ```bash
 caddy run --config ./Caddyfile
 ```
+
+### How to start Caddy as a Linux service
+
+Here are the 3 things you need to do to start Caddy as a system service:
+
+**a non-root user**
+
+If you don't have a non-root user, consider adding the `app` user with
+[`ssh-adduser`](https://webinstall.dev/ssh-adduser).
+
+Using a user named `app` to run your services is common industry convention.
+
+**port-binding privileges**
+
+You can use `setcap` to allow Caddy to use privileged ports.
+
+```bash
+sudo setcap cap_net_bind_service=+ep $(readlink $(command -v caddy))
+```
+
+**systemd config**
+
+You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
+start the appropriate systemd launcher for Linux.
+
+Install Serviceman with Webi:
+
+```bash
+webi serviceman
+```
+
+Use Serviceman to create a _systemd_ config file.
+
+```bash
+sudo env PATH="$PATH" \
+    serviceman --system --username $(whoami) --name caddy -- \
+        caddy run --config ./Caddyfile
+```
+
+This will create `/etc/systemd/system/caddy.service`, which can be managed with
+`systemctl`. For example:
+
+```bash
+sudo systemctl restart caddy
+```
+
+### How to start Caddy as a MacOS Service
+
+**Port-Binding Permission**
+
+Caddy must run as the `root` user in order to bind to ports 80 and 443.
+
+**launchd plist**
+
+You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
+start the appropriate service launcher file for MacOS.
+
+Install Serviceman with Webi:
+
+```bash
+webi serviceman
+```
+
+Use Serviceman to create a _launchd_ plist file.
+
+```bash
+serviceman --username $(whoami) --name caddy -- \
+    caddy run --config ./Caddyfile
+```
+
+This will create `~//Library/LaunchAgents/caddy.plist`, which can be managed
+with `launchctl`. For example:
+
+```bash
+launchctl unload -w "$HOME/Library/LaunchAgents/caddy.plist"
+launchctl load -w "$HOME/Library/LaunchAgents/caddy.plist"
+```
+
+### How to start Caddy as a Windows Service
+
+You may need to update the Windows Firewall to allow traffic through to Caddy.
+You'll also need to create a Startup entry in the registry, which can be done
+with Serviceman.
+
+**Windows Firewall**
+
+You can use PowerShell to update the firewall, which looks something like this:
+
+```pwsh
+powershell.exe -WindowStyle Hidden -Command $r = Get-NetFirewallRule -DisplayName 'Caddy Web Server' 2> $null; if ($r) {write-host 'found rule';} else {New-NetFirewallRule -DisplayName 'Go Web Server' -Direction Inbound C:\\Users\\YOUR_USER\\.local\\bin\\caddy.exe -Action Allow}
+```
+
+**Startup Registry**
+
+You can use [Serviceman](https://webinstall.dev/serviceman) to create and start
+the appropriate service launcher for Windows 10.
+
+Install Serviceman with Webi:
+
+```bash
+webi.bat serviceman
+```
+
+Use Serviceman to create a Startup entry in the Windows Registry:
+
+```bash
+serviceman.exe --name caddy -- \
+    caddy run --config ./Caddyfile
+```
+
+You can manage the service directly with Serviceman. For example:
+
+```bash
+serviceman stop caddy
+serviceman start caddy
+```
-- 
2.25.1