{"id":833,"date":"2026-08-08T23:25:47","date_gmt":"2026-08-08T23:25:47","guid":{"rendered":"https:\/\/virtualserversvps.com\/blog\/?p=833"},"modified":"2026-10-20T22:04:12","modified_gmt":"2026-10-20T22:04:12","slug":"caddy-reverse-proxy-setup-vps","status":"publish","type":"post","link":"https:\/\/virtualserversvps.com\/blog\/caddy-reverse-proxy-setup-vps\/","title":{"rendered":"Caddy as a Production Reverse Proxy: TLS, Health Checks, Logging and Measured Overhead"},"content":{"rendered":"
\n

Caddy is attractive precisely because it removes the two most error-prone parts of running a reverse proxy: writing TLS configuration and remembering to renew certificates. But the ten-minute setup is only half the job \u2014 a production proxy needs explicit upstream health checking, sensible timeouts, log hygiene, and a verification step that proves HTTPS actually issues on a real domain. This walkthrough builds that configuration from scratch, then measures it: handshake time, header overhead, and how it behaves when the upstream disappears. It assumes a clean Debian 12 or Ubuntu 24.04 instance on a small VPS with a public IPv4 address<\/a> and root access.<\/p>\n

Prerequisites and DNS Check<\/h2>\n

Caddy’s automatic HTTPS depends on inbound reachability on ports 80 and 443. Verify DNS before installing anything \u2014 a proxy that cannot complete the ACME challenge will spend several minutes retrying and then serve a self-signed cert, which looks like a TLS bug rather than a DNS one.<\/p>\n

<code>dig +short A app.example.com\ndig +short AAAA app.example.com\nss -lntp | grep -E ':(80|443)\\b'<\/code><\/code><\/pre>\n
If the A record points at the box and nothing is listening on 80\/443, you are ready. If you are behind a cloud load balancer or a CDN proxy, skip to the “TLS behind a proxy” section \u2014 automatic HTTP-01 challenges will not work.<\/p>\n
Install Caddy from the Official Repository<\/h2>\n
Distribution packages lag behind and may not include the ACME module versions you want. Use the official APT repository:<\/p>\n
<code>apt install -y debian-keyring debian-archive-keyring apt-transport-https curl\ncurl -1sLf 'https:\/\/dl.cloudsmith.io\/public\/caddy\/stable\/gpg.key' \\\n  | gpg --dearmor -o \/usr\/share\/keyrings\/caddy-stable-archive-keyring.gpg\ncurl -1sLf 'https:\/\/dl.cloudsmith.io\/public\/caddy\/stable\/debian.deb.txt' \\\n  | tee \/etc\/apt\/sources.list.d\/caddy-stable.list\napt update && apt install -y caddy\ncaddy version<\/code><\/code><\/pre>\n
Caddy runs as a systemd service with a dedicated caddy<\/code> user and stores certificates under \/var\/lib\/caddy\/.local\/share\/caddy<\/code>. Do not run it as root: caddy<\/code> binary capabilities handle the port-80\/443 bind for the service user via cap_net_bind_service<\/code> in the packaged unit.<\/p>\n
The Caddyfile<\/h2>\n
Start minimal and add capability deliberately. This configuration proxies an application on port 3000, adds compression, sets security headers, and writes structured access logs:<\/p>\n
<code>{\n    email ops@example.com\n    admin localhost:2019\n    servers {\n        timeouts {\n            read_body   30s\n            read_header 10s\n            write       60s\n            idle        120s\n        }\n    }\n}\n\napp.example.com {\n    encode zstd gzip\n\n    header {\n        Strict-Transport-Security \"max-age=31536000; includeSubDomains\"\n        X-Content-Type-Options \"nosniff\"\n        X-Frame-Options \"SAMEORIGIN\"\n        Referrer-Policy \"strict-origin-when-cross-origin\"\n        -Server\n    }\n\n    reverse_proxy 127.0.0.1:3000 {\n        health_uri \/healthz\n        health_interval 10s\n        health_timeout 2s\n        lb_try_duration 5s\n        lb_try_interval 250ms\n        header_up X-Real-IP {remote_host}\n        header_up X-Forwarded-Proto {scheme}\n    }\n\n    log {\n        output file \/var\/log\/caddy\/app.log {\n            roll_size 50mb\n            roll_keep 5\n            roll_keep_for 168h\n        }\n        format json\n    }\n}<\/code><\/code><\/pre>\n
Two entries do the heavy lifting. health_uri<\/code> makes Caddy actively probe the upstream instead of discovering failure from a user request \u2014 without it, a dead backend produces 502s until its own health check catches up. lb_try_duration<\/code> adds retry logic against the remaining upstreams for transient failures, which turns a rolling restart into an invisible event.<\/p>\n
Validate and Reload<\/h2>\n
Never reload an unvalidated Caddyfile. caddy validate<\/code> parses the config without touching the running process; caddy fmt<\/code> normalises it so diffs stay readable:<\/p>\n
<code>caddy fmt --overwrite \/etc\/caddy\/Caddyfile\ncaddy validate --config \/etc\/caddy\/Caddyfile --adapter caddyfile\nsystemctl reload caddy\njournalctl -u caddy -n 30 --no-pager<\/code><\/code><\/pre>\n
The admin API on port 2019 exposes live config for verification. Bind it to localhost only, as above \u2014 an open admin API allows arbitrary proxy reconfiguration:<\/p>\n
<code>curl -s localhost:2019\/config\/ | jq '.apps.http.servers | keys'\ncurl -s localhost:2019\/config\/apps\/tls\/certificates\/automate | jq<\/code><\/code><\/pre>\n
Verify Certificate Issuance<\/h2>\n
The whole point of Caddy is that this step should be boring. Prove it with three checks:<\/p>\n
<code>echo | openssl s_client -connect app.example.com:443 -servername app.example.com 2>\/dev\/null \\\n  | openssl x509 -noout -subject -issuer -dates -ext subjectAltName\n\ncurl -sSI https:\/\/app.example.com | head -5\ncurl -sS -o \/dev\/null -w '%{http_code} %{time_appconnect} %{time_total}\\n' https:\/\/app.example.com<\/code><\/code><\/pre>\n
Expected: issuer is Let’s Encrypt or ZeroSSL, notAfter<\/code> is about 90 days out, and http_code<\/code> is 200 with time_appconnect<\/code> (full handshake) typically 40\u201390 ms depending on network distance to the client. If the handshake takes 300 ms or more consistently, that is normal for a single round trip across an ocean but worth checking \u2014 TLS 1.3 brings it to one RTT, and session resumption brings returning visitors to zero extra round trips.<\/p>\n
Measure the Proxy Overhead<\/h2>\n
A reverse proxy adds latency; the question is whether it is 1 ms or 40 ms. Measure with a direct request against the upstream versus through Caddy on loopback:<\/p>\n
<code># direct to upstream\nwrk -t2 -c50 -d20s --latency http:\/\/127.0.0.1:3000\/\n\n# through Caddy over plain HTTP, no TLS in the path\nwrk -t2 -c50 -d20s --latency -H 'Host: app.example.com' http:\/\/127.0.0.1:80\/<\/code><\/code><\/pre>\n\n\n\n\n\n
Path<\/th>\nReq\/s<\/th>\np50<\/th>\np99<\/th>\n<\/tr>\n
Direct to app<\/td>\n8,900<\/td>\n5.4 ms<\/td>\n11 ms<\/td>\n<\/tr>\n
Via Caddy (HTTP)<\/td>\n7,600<\/td>\n6.3 ms<\/td>\n14 ms<\/td>\n<\/tr>\n
Via Caddy (HTTPS, TLS 1.3, resumed)<\/td>\n5,100<\/td>\n9.2 ms<\/td>\n21 ms<\/td>\n<\/tr>\n<\/table>\n
Roughly 0.9 ms added per request in the unencrypted path and about 2 ms with TLS and session resumption. On a dynamic application whose own handler takes 40 ms, that overhead is invisible. On a static file served straight from disk it is the dominant cost \u2014 which is the argument for letting Caddy serve static assets from its own cache layer with file_server<\/code> rather than proxying them at all.<\/p>\n
Failure Behaviour<\/h2>\n
Kill the upstream and observe. Caddy returns a 502 with a plain-text body by default. Replace it with something sane and make the failure fast:<\/p>\n
<code>handle_errors {\n    @5xx expression {err.status_code} >= 500\n    respond @5xx \"Upstream unavailable\" 503\n}<\/code><\/code><\/pre>\n
With lb_try_duration 5s<\/code> against a single dead upstream, Caddy will retry for the full window before answering. For a single-backend setup that is pure latency added to every failed request \u2014 set lb_try_duration<\/code> only when you have more than one upstream, or lower it to 1s. For multi-upstream setups the retry window is exactly what makes a rolling deploy clean.<\/p>\n
Operational Hygiene<\/h2>\n