Caching, Static and Proxy

Nginx caching: two caches, two different jobs

Your site is fast on the wire now. Caching makes it faster still by doing the work less often. Nginx caches in two places, and they solve different problems. Browser caching tells the visitor's browser to keep static files so it never asks again. Proxy caching keeps a copy of your app's responses on the server so your application does not have to generate the same page for every visitor. This chapter turns on both and proves each one is working.

Caching is the highest-leverage performance tool there is, because the work you never do is the work that costs nothing. A visitor who already has your CSS in their browser does not download it again. An app response that Nginx has cached does not touch your database again. Both are free once configured, and both are easy to get subtly wrong, so we will turn them on and then verify them rather than trust them.

Browser caching for static files

When a browser loads your page it fetches the HTML, then the CSS, the JavaScript, the fonts and images. Those static files rarely change, so making the browser re-download them on every visit is pure waste. expires fixes that with one line:

location /static/ {
    alias /var/www/app/static/;
    expires 30d;
    add_header Cache-Control "public";
}

expires 30d tells Nginx to send headers that say "keep this for thirty days." Confirm it on a real file:

curl -I https://your-domain/static/app.css

The response carries an Expires header thirty days in the future and Cache-Control: max-age=2592000, which is thirty days in seconds. From now on the browser serves that file from its own disk and does not ask your server at all until the time is up.

There is one catch worth understanding, because it is the reason people fear long cache times. If you cache app.css for thirty days and then change it, visitors keep the old version for up to thirty days. The professional answer is versioned filenames: your build tool names the file app.a1b2c3.css, and when the content changes the name changes, so the browser fetches the new name immediately while still caching each version forever. Cache aggressively, but only when the URL changes with the content.

Proxy caching for your app

Browser caching helps repeat visitors. Proxy caching helps everyone, including first-time visitors, by caching your application's responses on the server. If a hundred people load the same article, your app should generate it once and Nginx should serve the other ninety-nine copies from memory.

Set it up with a cache zone and a proxy_cache on the location:

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=app:10m max_size=1g;

server {
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_cache app;
        proxy_cache_valid 200 10m;
        add_header X-Cache-Status $upstream_cache_status;
    }
}

proxy_cache_path declares where cached responses live and names a shared memory zone, app, that tracks the keys. proxy_cache app turns caching on for this location. proxy_cache_valid 200 10m says cache successful responses for ten minutes. The last line is the one that makes caching visible: X-Cache-Status reports whether each response came from the cache or the app.

Now prove it. Request the same URL twice:

curl -I https://your-domain/

The first request shows X-Cache-Status: MISS: the cache was empty, so nginx went to your app and stored the result. The second request shows HIT: it was served entirely from cache, your app never saw it. That MISS then HIT is the whole proof that proxy caching is working, and it is the first thing to check when you are not sure whether a response is cached.

The rule that keeps you out of trouble

Proxy caching has one genuine danger, and it is worth stating bluntly: if you cache a response that was meant for one specific user, Nginx will serve that same private page to the next person. Cache a logged-in dashboard once and every visitor sees the first user's account.

So the rule is simple. Cache public, identical-for-everyone responses: your marketing pages, blog posts, product listings, public API results. Never cache anything personalised or authenticated. In practice you exclude the risky paths and honour the app's own instructions:

proxy_cache_bypass $cookie_session;
proxy_no_cache     $cookie_session;

These two lines tell Nginx to skip the cache entirely when a session cookie is present, so logged-in requests always go straight to the app. Combined with your app sending Cache-Control: no-store on private responses, which Nginx respects, you get the speed of caching on public pages with no risk of leaking private ones. When in doubt, do not cache it. A cache miss is slow; a cache leak is a security incident.

Going further: purging when you must

Sometimes you change a page and cannot wait for the cache to expire. The open-source Nginx does not include active purge, but you have two clean options. The simplest is a short proxy_cache_valid so stale content self-corrects quickly, which is enough for most content.

When you need instant invalidation, the common pattern is to key the cache so a content change produces a new key, the same versioning idea as static files, so the old cached copy is simply never requested again. Reach for a purge module only when you genuinely need to evict a specific live URL on demand.

Frequently asked questions

Recap and what is next

You can make repeat visitors re-download nothing with browser caching, serve your app's public pages from cache so your application does the work once instead of once per visitor, and prove both are working by reading the cache headers rather than guessing. You know the one rule that keeps proxy caching safe: public yes, private never. Your server is now fast and doing far less work.

Speed is only half of production, though. Next we keep the server standing under abuse, with rate limiting, so one flood cannot undo everything you just built.