Caddy Performance Optimization
Caddy is fast out of the box, so performance work on it is rarely about making the server itself faster. It is about removing work: not compressing a response that a browser will cache anyway, not opening a new TCP connection to the backend for every request, not writing an access log line for a health probe that fires every ten seconds. By the end of this page you will be able to measure where the time actually goes, enable the protocol versions that cut handshake cost, compress responses on the wire, control caching precisely, size timeouts and connection pools sensibly, and remove the logging overhead that quietly dominates a busy deployment.
Guessing at bottlenecks is the most common way to make a server slower, so get a baseline first. If the first byte arrives quickly and the total time is long, the bottleneck is the body size and compression or caching is the fix. If the first byte is slow, the bottleneck is upstream or on the network.
curl -o /dev/null -s -w "tls:%{time_appconnect} ttfb:%{time_starttransfer} total:%{time_total}\n" https://example.com/
hey -n 5000 -c 50 https://example.com/
HTTP/2 multiplexes many requests over one connection, removing the cost of a connection per request. HTTP/3 runs over QUIC, which removes the TCP handshake entirely. Caddy enables both by default, so the useful action is usually to restrict them rather than to switch them on.
{
servers {
protocols h1 h2 h3
}
}
Early data, also called 0-RTT, lets a returning client send request data in the first round trip. It is enabled by default on QUIC listeners, and you should disable it with servers { 0rtt off } if you use a remote_ip matcher, because routing on the client address before the handshake completes forces a retry.
The encode directive compresses responses on the fly. Caddy supports zstd and gzip, and it chooses based on the Accept-Encoding header the client sent.
example.com {
encode zstd gzip {
minimum_length 512
}
}
minimum_length avoids spending CPU on a response too small to benefit; the default of 512 bytes is a sensible starting point. For static assets, compressing at build time is better than compressing on every request: generate the compressed sibling files during your build with brotli and gzip, then let the file server pick them up.
example.com {
root * /srv/www
file_server {
precompressed br gzip
}
}
With precompressed, Caddy serves the .br or .gz file when the client accepts that encoding and falls back to the original otherwise. Nothing is compressed at request time.
The file server already sends ETag and Last-Modified, so browsers revalidate static content correctly. What you usually want to add is an explicit cache lifetime for content that has a hashed name and never changes.
example.com {
root * /srv/www
@assets path /assets/*
header @assets Cache-Control "public, max-age=31536000, immutable"
@html path *.html /
header @html Cache-Control "public, max-age=0, must-revalidate"
file_server
}
Long-lived caching for fingerprinted assets and immediate revalidation for HTML is the pairing that avoids stale pages while keeping the bulk of the traffic off the network. Caddy does not implement a shared cache itself; when you need surrogate caching in front of an application, put a caching layer in front of Caddy.
Slow clients and malformed requests are the two ways a server is degraded. The servers global option sets the timeouts that apply to every listener.
{
servers {
timeouts {
read_header 10s
read_body 30s
write 60s
idle 5m
}
keepalive_idle_conns 256
keepalive_idle_conns_per_host 32
max_header_size 32KiB
}
}
read_header bounds how long a client may take to send its headers, which is the classic slowloris defence. read_body bounds an upload, write bounds the response delivery, and idle bounds how long a keep-alive connection may sit unused. The keepalive settings size the pool of idle client connections, and max_header_size caps how much header data Caddy parses at all, answering with status 431 beyond the limit.
Every upstream request that opens a fresh TCP connection pays for a handshake, so the transport settings decide whether Caddy reuses connections.
example.com {
reverse_proxy {
to backend-1:9000 backend-2:9000
transport http {
keepalive 30s
keepalive_idle_conns 64
keepalive_idle_conns_per_host 16
read_buffer 64KiB
max_conns_per_host 256
}
}
}
keepalive sets how long an idle upstream connection is kept, keepalive_idle_conns is the total pool size, and keepalive_idle_conns_per_host is the per-backend portion of it. max_conns_per_host caps how many connections to a single backend may be open at once, protecting a fragile backend from a flood. Raising read_buffer above the 4KiB default avoids truncating large response header sets.
An access log line is cheap to write and expensive at scale, so under a heavy probe or an attack, logging can cost more than serving the requests.
example.com {
log {
output discard
}
}
To keep logging but reduce its volume, use sampling, which logs the first requests in each window and then samples the rest.
example.com {
log {
sampling {
interval 1m
first 100
}
}
}
The log_skip directive excludes matching requests from the log entirely, which is the right tool for health probes and internal monitoring.
Prometheus metrics have to be turned on in the global options block and then exposed by the metrics directive. The endpoint returns the Prometheus exposition format, or the OpenMetrics format when the client negotiates it, and Prometheus scrapes the admin endpoint by default.
{
metrics {
per_host
}
}
metrics.example.com {
metrics
}
| Change | Effect | Cost |
|---|---|---|
encode zstd gzip | Smaller responses over the wire | A little CPU per response |
precompressed with build-time assets | No compression cost at request time | Build pipeline work |
Long Cache-Control on fingerprinted assets | Most requests never reach the server | Requires immutable URLs |
Upstream keepalive | No TCP handshake per request | Idle connections held open |
log { output discard } or sampling | Removes per-request I/O | Loses access history |
read_header and max_header_size | Limits exposure to slow or malformed clients | Long uploads may be cut off |
Approach:
The site serves a single-page application with hashed asset bundles plus an HTML entry point, and proxies an API to one backend. The measurement shows a slow time to first byte on the HTML and a large body on the bundles, while the backend reports a new connection for every request. The plan therefore attacks three separate costs: transfer size for the bundles, round trips for the API, and per-request logging overhead.
Steps:
- Enable zstd and gzip compression with a minimum length, so only responses large enough to benefit are compressed.
- Pre-compress the asset bundles at build time and let the file server serve the siblings with
precompressed, which removes compression from the request path entirely. - Give the hashed assets a one-year immutable cache lifetime and keep the HTML entry point on a revalidating policy, so repeat visitors do not download the bundles again.
- Turn on upstream connection reuse with a thirty second keepalive and a sensible pool size, so the API no longer pays for a TCP handshake per request.
- Reduce logging volume with sampling rather than disabling the log, so a burst of traffic does not become a burst of disk writes while recent history is still retained.
- Turn on Prometheus metrics in the global options and expose them on a dedicated host, so the effect of each change can be verified instead of assumed.
Answer:
The tuned configuration is:
{
email admin@example.com
metrics {
per_host
}
servers {
protocols h1 h2 h3
timeouts {
read_header 10s
write 60s
idle 5m
}
}
}
metrics.example.com {
metrics
}
example.com {
root * /srv/www
encode zstd gzip {
minimum_length 512
}
@assets path /assets/*
header @assets Cache-Control "public, max-age=31536000, immutable"
@html path *.html /
header @html Cache-Control "public, max-age=0, must-revalidate"
log {
sampling {
interval 1m
first 100
}
}
file_server {
precompressed br gzip
}
handle_path /api/* {
reverse_proxy {
to backend-1:9000
transport http {
keepalive 30s
keepalive_idle_conns 64
read_buffer 64KiB
}
}
}
}With this configuration the bundle transfer shrinks to roughly a quarter of its original size, a returning visitor fetches the HTML but not the bundles, the API reuses warm upstream connections, and the access log records a bounded number of lines per minute. Running hey -n 5000 -c 50 https://example.com/ before and after the change shows the improvement in time to first byte and in total requests per second.
