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
```
projects / webi-installers / .git / blobdiff