3 homepage: https://github.com/caddyserver/caddy
5 Caddy is a fast, multi-platform web server with automatic HTTPS.
14 Use the `@beta` tag for pre-releases, or `@x.y.z` for a specific version.
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.
22 Here's the things we find most useful:
24 - Simple File & Directory Server
25 - Reverse Proxy with www (and HTTPS) redirects
26 - Running as a system service on
31 ### How to serve a directory
34 caddy file-server --browse --listen :4040
37 ### How to redirect and reverse proxy
39 Here's what a fairly basic `Caddyfile` looks like:
42 # redirect www to bare domain
44 redir https://example.com{uri} permanent
48 # log to stdout, which is captured by journalctl
54 # turn on standard streaming compression
57 # reverse proxy /api to :3000
58 reverse_proxy /api/* localhost:3000
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
64 # serve static files from public folder, but not /api
67 try_files {path} {path}/ {path}/index.html
70 not path /.well-known/openid-configuration
71 not path /.well-known/jwks.json
74 rewrite @notApi {http.matchers.file.relative}
76 root * /srv/example.com/public/
81 And here's how you run caddy with it:
84 caddy run --config ./Caddyfile
87 ### How to start Caddy as a Linux service
89 Here are the 3 things you need to do to start Caddy as a system service:
93 If you don't have a non-root user, consider adding the `app` user with
94 [`ssh-adduser`](https://webinstall.dev/ssh-adduser).
96 Using a user named `app` to run your services is common industry convention.
98 **port-binding privileges**
100 You can use `setcap` to allow Caddy to use privileged ports.
103 sudo setcap cap_net_bind_service=+ep $(readlink $(command -v caddy))
108 You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
109 start the appropriate systemd launcher for Linux.
111 Install Serviceman with Webi:
117 Use Serviceman to create a _systemd_ config file.
120 sudo env PATH="$PATH" \
121 serviceman add --system --username $(whoami) --name caddy -- \
122 caddy run --config ./Caddyfile
125 This will create `/etc/systemd/system/caddy.service`, which can be managed with
126 `systemctl`. For example:
129 sudo systemctl restart caddy
132 ### How to start Caddy as a MacOS Service
134 **Port-Binding Permission**
136 Caddy must run as the `root` user in order to bind to ports 80 and 443.
140 You can use [`serviceman`](https://webinstall.dev/serviceman) to create and
141 start the appropriate service launcher file for MacOS.
143 Install Serviceman with Webi:
149 Use Serviceman to create a _launchd_ plist file.
152 serviceman add --username $(whoami) --name caddy -- \
153 caddy run --config ./Caddyfile
156 This will create `~//Library/LaunchAgents/caddy.plist`, which can be managed
157 with `launchctl`. For example:
160 launchctl unload -w "$HOME/Library/LaunchAgents/caddy.plist"
161 launchctl load -w "$HOME/Library/LaunchAgents/caddy.plist"
164 ### How to start Caddy as a Windows Service
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
172 You can use PowerShell to update the firewall, which looks something like this:
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}
180 You can use [Serviceman](https://webinstall.dev/serviceman) to create and start
181 the appropriate service launcher for Windows 10.
183 Install Serviceman with Webi:
189 Use Serviceman to create a Startup entry in the Windows Registry:
192 serviceman.exe add --name caddy -- \
193 caddy run --config ./Caddyfile
196 You can manage the service directly with Serviceman. For example:
199 serviceman stop caddy
200 serviceman start caddy