Caddy
An extensible web server and reverse proxy with automatic HTTPS workflows, simple site configuration and support for static files and upstream applications.
What Caddy is for
Caddy serves static files and proxies requests to upstream applications through a concise configuration model. It can automate HTTPS certificate workflows when DNS, ports and domain ownership are correctly configured. The web server is still part of the deployment boundary: upstream paths, headers, logs and secrets need review.
Make the site block explicit
A site address, document root and upstream target should be clear before adding redirects or header rules. Validate the configuration, inspect the rendered behavior and keep a known-good copy before reloads. Avoid mixing development and production credentials in one configuration directory.
HTTPS depends on the surrounding system
Certificate automation needs a reachable domain, correct DNS, open challenge paths and a process that can bind the expected ports. A valid certificate does not prove that the upstream application, cookies, security headers or access rules are correct.
Maintenance note
This page reviews Caddy site blocks, reverse proxying, static files, automatic HTTPS prerequisites, logs and configuration validation. Content review date: 2026-08-23.
Save to your cloud drive
Open the cloud drive to get the file directly, or save it for convenient access on another device.
Quark Cloud Drive
RecommendedSave Caddy to this cloud drive
Baidu Netdisk
Save Caddy to this cloud drive
Caddy static site and reverse proxy setup
Serve a small test site first, validate the site block and upstream health, then enable the production domain and certificate workflow with logs available for inspection.
Before you start
- Confirm the domain resolves to the server and identify the document root or upstream application port.
- Reserve a backup of the current configuration and a safe way to restore the previous version.
- Ensure ports, firewall rules and the ACME challenge path are compatible with the certificate method.
Installation steps
- 01
Install and inspect the service
Install the matching Caddy package, check the service user, configuration path and log destination, and do not copy unknown production credentials into the test setup.
- 02
Define a minimal site block
Set the site address, static root or upstream target and only the required headers, then validate the configuration before reloading.
- 03
Test locally and by domain
Request the local site and the domain separately, inspect status codes and upstream headers, and confirm that the intended path reaches the intended application.
Quick start
- 01
Add the reverse proxy route
Point the proxy to the application port, check forwarded headers and timeouts, and verify a health endpoint before serving real traffic.
- 02
Enable HTTPS prerequisites
Confirm DNS, port reachability, challenge path access and certificate storage permissions, then monitor logs during the first issuance attempt.
- 03
Reload with a rollback copy
Keep the last valid configuration, validate the new file, reload the service and immediately test home, resource, API and error paths.
Usage tips
- Certificates, reverse-proxy headers and upstream authentication solve different problems and should be reviewed separately.
- Do not expose admin or database ports through a broad proxy rule; define public paths explicitly.
- Keep logs useful but avoid writing tokens, session cookies or complete personal data into them.
Troubleshooting and uninstall
Why does automatic HTTPS fail?
Check DNS, domain reachability, ports, firewall rules, challenge paths, clock and certificate storage permissions, then inspect the service log for the first error.
Why does the proxy return 502?
Confirm that the upstream process is running and listening on the expected address, then check container networking, protocol, timeout and forwarded-header assumptions.
- Save the working configuration and certificatesExport the known-good configuration, document the upstream and domain mapping and retain certificates only according to the deployment policy.
- Stop and remove CaddyStop the service, remove the package through the operating system and clean temporary logs or configuration only after another server has taken over the domain.
Frequently asked questions
Does a valid Caddy certificate prove that the application is configured correctly?
No. It proves certificate issuance for the domain. Upstream routing, cookies, headers, authentication and access controls still need separate checks.
What does a 502 response usually indicate?
The proxy could not reach or understand the upstream application. Check the process, address, port, protocol, container network and timeout.
Why should the ACME challenge path stay available?
Certificate renewal methods may need to reach the challenge path. A broad deny rule or proxy change can interrupt renewal even when ordinary pages still work.