caddy/README.md

   1 ---
   2 title: Caddy
   3 homepage: https://github.com/caddyserver/caddy
   4 tagline: |
   5   Caddy is a fast, multi-platform web server with automatic HTTPS.
   6 ---
   7
   8 To update or switch versions, run `webi caddy@stable` (or `@v2.4`, `@beta`,
   9 etc).
  10
  11 ## Cheat Sheet
  12
  13 > Caddy makes it easy to use Let's Encrypt to handle HTTPS (TLS/SSL) and to
  14 > reverse proxy APIs and WebSockets to other apps - such as those written node,
  15 > Go, python, ruby, and PHP.
  16
  17 Here's the things we find most useful:
  18
  19 - Simple File & Directory Server
  20 - Reverse Proxy with www (and HTTPS) redirects
  21 - Running as a system service on
  22   - Linux
  23   - MacOS
  24   - Windows 10
  25
  26 ### How to serve a directory
  27
  28 ```bash
  29 caddy file-server --browse --listen :4040
  30 ```
  31
  32 ### How to redirect and reverse proxy
  33
  34 Here's what a fairly basic `Caddyfile` looks like:
  35
  36 ```txt
  37 # redirect www to bare domain
  38 www.example.com {
  39     redir https://example.com{uri} permanent
  40 }
  41
  42 example.com {
  43     # log to stdout, which is captured by journalctl
  44     log {
  45         output stdout
  46         format console
  47     }
  48
  49     # turn on standard streaming compression
  50     encode gzip zstd
  51
  52     # reverse proxy /api to :3000
  53     reverse_proxy /api/* localhost:3000
  54
  55     # reverse proxy some "well known" APIs
  56     reverse_proxy /.well-known/openid-configuration localhost:3000
  57     reverse_proxy /.well-known/jwks.json localhost:3000
  58
  59     # serve static files from public folder, but not /api
  60     @notApi {
  61         file {
  62             try_files {path} {path}/ {path}/index.html
  63         }
  64         not path /api/*
  65         not path /.well-known/openid-configuration
  66         not path /.well-known/jwks.json
  67     }
  68     route {
  69       rewrite @notApi {http.matchers.file.relative}
  70     }
  71     root * /srv/example.com/public/
  72     file_server
  73 }
  74 ```
  75
  76 And here's how you run caddy with it:
  77
  78 ```bash
  79 caddy run --config ./Caddyfile
  80 ```
  81
  82 ### How to start Caddy as a Linux service
  83
  84 Here are the 3 things you need to do to start Caddy as a system service:
  85
  86 **a non-root user**
  87
  88 If you don't have a non-root user, consider adding the `app` user with
  89 [`ssh-adduser`](https://webinstall.dev/ssh-adduser).
  90
  91 Using a user named `app` to run your services is common industry convention.
  92
  93 **port-binding privileges**
  94
  95 You can use `setcap` to allow Caddy to use privileged ports.
  96
  97 ```bash
  98 sudo setcap cap_net_bind_service=+ep $(readlink -f $(command -v caddy))
  99 ```
 100
 101 **systemd config**
 102
 103 You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
 104 start the appropriate systemd launcher for Linux.
 105
 106 Install Serviceman with Webi:
 107
 108 ```bash
 109 webi serviceman
 110 ```
 111
 112 Use Serviceman to create a _systemd_ config file.
 113
 114 ```bash
 115 sudo env PATH="$PATH" \
 116     serviceman add --system --username $(whoami) --name caddy -- \
 117         caddy run --config ./Caddyfile
 118 ```
 119
 120 This will create `/etc/systemd/system/caddy.service`, which can be managed with
 121 `systemctl`. For example:
 122
 123 ```bash
 124 sudo systemctl restart caddy
 125 ```
 126
 127 ### How to start Caddy as a MacOS Service
 128
 129 **Port-Binding Permission**
 130
 131 Caddy must run as the `root` user in order to bind to ports 80 and 443.
 132
 133 **launchd plist**
 134
 135 You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
 136 start the appropriate service launcher file for MacOS.
 137
 138 Install Serviceman with Webi:
 139
 140 ```bash
 141 webi serviceman
 142 ```
 143
 144 Use Serviceman to create a _launchd_ plist file.
 145
 146 ```bash
 147 serviceman add --username $(whoami) --name caddy -- \
 148     caddy run --config ./Caddyfile
 149 ```
 150
 151 This will create `~//Library/LaunchAgents/caddy.plist`, which can be managed
 152 with `launchctl`. For example:
 153
 154 ```bash
 155 launchctl unload -w "$HOME/Library/LaunchAgents/caddy.plist"
 156 launchctl load -w "$HOME/Library/LaunchAgents/caddy.plist"
 157 ```
 158
 159 ### How to start Caddy as a Windows Service
 160
 161 You may need to update the Windows Firewall to allow traffic through to Caddy.
 162 You'll also need to create a Startup entry in the registry, which can be done
 163 with Serviceman.
 164
 165 **Windows Firewall**
 166
 167 You can use PowerShell to update the firewall, which looks something like this:
 168
 169 ```pwsh
 170 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}
 171 ```
 172
 173 **Startup Registry**
 174
 175 You can use [Serviceman](https://webinstall.dev/serviceman) to create and start
 176 the appropriate service launcher for Windows 10.
 177
 178 Install Serviceman with Webi:
 179
 180 ```bash
 181 webi.bat serviceman
 182 ```
 183
 184 Use Serviceman to create a Startup entry in the Windows Registry:
 185
 186 ```bash
 187 serviceman.exe add --name caddy -- \
 188     caddy run --config ./Caddyfile
 189 ```
 190
 191 You can manage the service directly with Serviceman. For example:
 192
 193 ```bash
 194 serviceman stop caddy
 195 serviceman start caddy
 196 ```