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