Learning nginx - HTTP Caching & Microcaching

#Introduction

Application backends are expensive to run. Every request means processing, database queries, and CPU. NGINX offers a powerful weapon: HTTP caching. Cached responses no longer touch the backend, so throughput can increase dramatically. This Episode 8 covers caching and microcaching.

You'll set up cache storage with proxy_cache_path, enable it in a location with proxy_cache and proxy_cache_valid, monitor effectiveness via the X-Cache-Status header, and apply microcaching techniques to survive sudden traffic spikes.

#The Benefits of Caching in NGINX

#Reducing Load, Raising Throughput

When NGINX handles the same request repeatedly, the cache stores the full response on disk. Subsequent requests are served straight from the cache without touching the backend at all:

• Backend load drops dramatically: the database and CPU are no longer burdened with identical requests.
• Latency drops: responses come from a cache sitting close to the client.
• Throughput rises: NGINX can serve thousands of requests per second per worker.

Keep in mind: caching isn't the solution for all content. Per-user private content, like profile pages, must be handled carefully so it doesn't leak between users.

#proxy_cache Configuration

#Setting Up the Storage Path

The cache is declared in the http context with proxy_cache_path:

http {
    proxy_cache_path /var/cache/nginx
                     keys_zone=my_cache:10m
                     levels=1:2
                     max_size=1g
                     inactive=60m;
}

• keys_zone=my_cache:10m — the zone name and metadata size in memory.
• levels=1:2 — a two-level directory structure to avoid one folder holding millions of files.
• max_size=1g — the disk size limit of the cache.
• inactive=60m — entries not accessed for 60 minutes are cleaned up.

#Enabling the Cache in a Location

Enable the zone in the locations you want:

location / {
    proxy_pass http://backend_app;
 
    proxy_cache my_cache;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
}

proxy_cache_valid 200 302 10m; stores responses with status 200 and 302 for 10 minutes. The additional line gives a different rule for 404 statuses.

#Cache Status Header

#Monitoring Effectiveness with X-Cache-Status

Add a header so every response shows where the data came from:

location / {
    proxy_pass http://backend_app;
    proxy_cache my_cache;
    proxy_cache_valid 200 302 10m;
 
    add_header X-Cache-Status $upstream_cache_status;
}

The value of $upstream_cache_status can be:

• HIT — served from the cache.
• MISS — not found in the cache, fetched from the backend.
• EXPIRED — cache expired, refreshed from the backend.
• BYPASS — cache intentionally skipped.
• UPDATING — the old entry is served while a refresh takes place.

Verify with curl:

curl -I http://localhost/
curl -I http://localhost/

Run curl -I twice in a row: the first response is MISS, the second is HIT. That's proof the cache is working.

#The Microcaching Technique

#Surviving Flash Crowds

Microcaching stores dynamic responses for a very short time, usually 1-5 seconds. The goal isn't saving on average load, but protecting the backend from flash crowds — sudden traffic spikes, for example when a link goes viral or during a major event.

location / {
    proxy_pass http://backend_app;
    proxy_cache my_cache;
    proxy_cache_valid 200 302 1s;
    proxy_cache_lock on;
    proxy_cache_use_stale updating error timeout;
}

• proxy_cache_valid 200 302 1s; — the cache only lasts 1 second.
• proxy_cache_lock on; — when cache misses happen simultaneously, only one request is forwarded to the backend; the rest wait.
• proxy_cache_use_stale updating; — while the cache refreshes, clients still receive the old version.

With microcaching, a thousand requests arriving within one second only let one touch the backend. Traffic spikes stop bringing the application down.

#When to Use Caching

#Choosing the Right Strategy

• Public pages that rarely change: cache for 10-60 minutes.
• Dynamic pages prone to traffic floods: microcache for 1-5 seconds.
• Per-user content: don't cache at the NGINX level without a key that separates users.
• APIs with confidential responses: make sure they never enter the public cache.

Always test the cache flow with two consecutive curls and read the X-Cache-Status header.

#Conclusion

Episode 8 gave you full control over NGINX caching: setting up the storage zone, enabling per-location caching, monitoring effectiveness through the status header, and applying microcaching for resilience against traffic spikes.

Key takeaways:

• Caching reduces backend load and significantly raises throughput.
• proxy_cache_path defines the storage zone and its cleanup rules.
• proxy_cache_valid sets how long responses are stored per status code.
• X-Cache-Status shows HIT, MISS, EXPIRED, or UPDATING.
• Microcaching of 1-5 seconds protects against flash crowds.
• proxy_cache_lock and proxy_cache_use_stale keep the cache fast on misses.

In the next episode we'll secure NGINX with SSL/TLS (HTTPS) and Let's Encrypt — TLS encryption concepts, manual HTTPS server blocks, free certificate automation with Certbot, auto-renewal, and HTTP to HTTPS redirects.