Boost Web Performance: Master Nginx Content Caching in Minutes

Overview

Content caching sits between the client and the upstream server, storing copies of responses so that subsequent requests can be served directly from the cache, reducing latency and offloading the application server.

Multiple cache layers may exist: browser cache, intermediate caches, CDNs, and reverse‑proxy caches such as Nginx. Even at the reverse‑proxy level, caching can dramatically improve performance.

How to Set Up Basic Cache

Only two directives are required: proxy_cache_path to define the cache location and parameters, and proxy_cache to enable it.

proxy_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=10g 
                 inactive=60m use_temp_path=off;

server {
    # ...
    location / {
        proxy_cache my_cache;
        proxy_pass http://my_upstream;
    }
}

The proxy_cache_path parameters mean:

Cache directory is /path/to/cache/. levels creates a two‑level directory hierarchy to avoid too many files in a single directory. keys_zone allocates shared memory for cache keys (10 MB can hold ~80 000 keys). max_size limits the cache size (10 GB in the example). inactive removes items not accessed for 60 minutes. use_temp_path=off writes temporary files directly to the cache directory.

The proxy_cache directive activates caching for the matching location.

Serving Stale Content When Upstream Is Down

Nginx can return stale cached content if the upstream server is unavailable by using proxy_cache_use_stale:

location / {
    # ...
    proxy_cache_use_stale error timeout http_500 http_502 http_503 http_504;
}

This returns the expired file instead of propagating the error to the client.

Improving Cache Performance

Additional directives can fine‑tune caching:

proxy_cache_path /path/to/cache levels=1:2 keys_zone=my_cache:10m max_size=10g 
                 inactive=60m use_temp_path=off;

server {
    # ...
    location / {
        proxy_cache my_cache;
        proxy_cache_revalidate on;
        proxy_cache_min_uses 3;
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;
        proxy_cache_lock on;
        proxy_pass http://my_upstream;
    }
}

Key options: proxy_cache_revalidate forces conditional GETs to refresh stale content. proxy_cache_min_uses caches an item only after it has been requested a certain number of times (default 1). proxy_cache_background_update serves stale content while the fresh version is fetched in the background. proxy_cache_lock ensures only one request populates the cache for a miss.

Splitting Cache Across Multiple Disks

When multiple disks are available, cache can be distributed using separate proxy_cache_path entries and the split_clients directive:

proxy_cache_path /path/to/hdd1 levels=1:2 keys_zone=my_cache_hdd1:10m max_size=10g inactive=60m use_temp_path=off;
proxy_cache_path /path/to/hdd2 levels=1:2 keys_zone=my_cache_hdd2:10m max_size=10g inactive=60m use_temp_path=off;

split_clients $request_uri $my_cache {
    50% "my_cache_hdd1";
    50% "my_cache_hdd2";
}

server {
    # ...
    location / {
        proxy_cache $my_cache;
        proxy_pass http://my_upstream;
    }
}

This method does not replace RAID; a disk failure can still cause errors.

Detecting Cache Status

Add the upstream cache status to response headers:

add_header X-Cache-Status $upstream_cache_status;

Possible values are MISS, BYPASS, EXPIRED, STALE, UPDATING, REVALIDATED, and HIT.

Cache Key Customization

The default cache key is an MD5 hash of $scheme$proxy_host$request_uri. It can be changed with proxy_cache_key, for example to include a cookie:

proxy_cache_key $proxy_host$request_uri$cookie_jessionid;

This treats the same URI with different JSESSIONID values as separate cache entries.

Other Useful Directives

proxy_ignore_headers Cache-Control

– ignore Cache‑Control headers. proxy_ignore_headers Set-Cookie – ignore Set‑Cookie headers. proxy_cache_methods GET HEAD POST – enable caching for POST requests. proxy_cache_bypass – force a request to bypass the cache.

Conclusion

Understanding and correctly configuring Nginx proxy caching can significantly improve web application performance and reliability. Use the directives above to tailor caching behavior to your specific needs.