docs: add -- global flag
[webi-installers/.git] / 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 ```