X-Git-Url: https://git.josue.xyz/?a=blobdiff_plain;f=caddy%2FREADME.md;h=d674bc3219471670be08bef825ff77a3d75f4a52;hb=refs%2Fremotes%2Forigin%2FHEAD;hp=f7f4ae56d8dc344f193170848007ef615969ee9e;hpb=1ddaa43a7dbfd819edb190152f88a02d6b81c110;p=webi-installers%2F.git

diff --git a/caddy/README.md b/caddy/README.md
index f7f4ae5..d674bc3 100644
--- a/caddy/README.md
+++ b/caddy/README.md
@@ -3,10 +3,194 @@ title: Caddy
 homepage: https://github.com/caddyserver/caddy
 tagline: |
   Caddy is a fast, multi-platform web server with automatic HTTPS.
-description: |
-  Caddy makes it easy to use Let's Encrypt to handle HTTPS (TLS/SSL) and to reverse proxy APIs and WebSockets to other apps - such as those written node, Go, python, ruby, and PHP.
 ---
 
+To update or switch versions, run `webi caddy@stable` (or `@v2.4`, `@beta`,
+etc).
+
+## Cheat Sheet
+
+> Caddy makes it easy to use Let's Encrypt to handle HTTPS (TLS/SSL) and to
+> 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
+caddy file-server --browse --listen :4040
+```
+
+### How to redirect and reverse proxy
+
+Here's what a fairly basic `Caddyfile` looks like:
+
+```txt
+# redirect www to bare domain
+www.example.com {
+    redir https://example.com{uri} permanent
+}
+
+example.com {
+    # log to stdout, which is captured by journalctl
+    log {
+        output stdout
+        format console
+    }
+
+    # turn on standard streaming compression
+    encode gzip zstd
+
+    # 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}
+    }
+    root * /srv/example.com/public/
+    file_server
+}
+```
+
+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 -f $(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 add --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 add --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 add --name caddy -- \
+    caddy run --config ./Caddyfile
+```
+
+You can manage the service directly with Serviceman. For example:
+
 ```bash
-caddy start
+serviceman stop caddy
+serviceman start caddy
 ```