Micro-caching for dynamic content in Nginx - Commands & Configuration

Introduction

Sometimes dynamic websites take longer to respond because they generate content on the fly. Micro-caching helps by saving these dynamic pages for a very short time, so repeated requests get faster responses without waiting for full processing.

When your website has pages that change often but can be reused for a few seconds to reduce server load.

When you want to speed up API responses that are dynamic but tolerate a few seconds delay in showing new data.

When your server is slow to generate pages and you want to handle sudden bursts of traffic smoothly.

When you want to reduce database queries by caching dynamic content briefly.

When you want to improve user experience by serving faster responses without losing fresh content.

Config File - nginx.conf

nginx.conf

http {
    proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=microcache:10m max_size=100m inactive=60m use_temp_path=off;

    server {
        listen 80;
        server_name example.com;

        location / {
            proxy_cache microcache;
            proxy_cache_valid 200 5s;
            proxy_cache_use_stale error timeout updating;
            proxy_pass http://backend_server;
            add_header X-Cache-Status $upstream_cache_status always;
        }
    }
}

proxy_cache_path defines where cache files are stored and how much memory is used for keys.

proxy_cache enables caching for this location using the defined cache zone.

proxy_cache_valid 200 5s caches successful responses for 5 seconds (micro-cache).

proxy_cache_use_stale serves stale content if backend is slow or down.

add_header X-Cache-Status adds a header to show if response was served from cache.

Commands

Check the nginx configuration file syntax to ensure there are no errors before reloading.

Terminal

sudo nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload nginx to apply the new configuration without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Send a request to the server and check headers to see if the response is cached (look for X-Cache-Status).

Terminal

curl -I http://example.com/

Expected Output

HTTP/1.1 200 OK

Server: nginx

X-Cache-Status: MISS

Date: Thu, 01 Jun 2023 12:00:00 GMT

Content-Type: text/html

Content-Length: 1234

Connection: keep-alive

Send the same request again shortly after to verify the response is served from cache (X-Cache-Status: HIT).

Terminal

curl -I http://example.com/

Expected Output

HTTP/1.1 200 OK

Server: nginx

X-Cache-Status: HIT

Date: Thu, 01 Jun 2023 12:00:02 GMT

Content-Type: text/html

Content-Length: 1234

Connection: keep-alive

Key Concept

If you remember nothing else from this pattern, remember: micro-caching stores dynamic content for a few seconds to speed up responses and reduce server load without losing freshness.

Common Mistakes

Setting micro-cache duration too long, like minutes or hours.

This causes users to see outdated dynamic content, defeating the purpose of micro-caching.

Use very short cache times like 5 seconds to keep content fresh but still gain speed.

Not testing nginx configuration before reload.

A syntax error can cause nginx to fail to reload, making the site unavailable.

Always run 'sudo nginx -t' to check config syntax before reloading.

Not adding headers to verify cache status.

Without headers, it's hard to confirm if micro-caching works or troubleshoot issues.

Add 'add_header X-Cache-Status $upstream_cache_status always;' to see cache hits and misses.

Summary

Define a cache zone with proxy_cache_path to store cached files.

Enable caching in the server location with proxy_cache and set a short cache time using proxy_cache_valid.

Reload nginx after configuration changes and verify caching works by checking response headers.