Cache-Control headers in Nginx - Commands & Configuration

Introduction

Web browsers and proxies can store copies of your website files to load pages faster. Cache-Control headers tell these browsers how long to keep these copies before asking for fresh ones. This helps your site load quickly while showing updated content when needed.

When you want browsers to keep images and stylesheets for a day to speed up page loading.

When you update your website often and want browsers to check for new content every time.

When you serve files that rarely change and want to reduce server load by letting browsers cache them longer.

When you want to prevent sensitive pages from being stored in browser cache for security reasons.

When you want to control how proxies cache your content between your server and users.

Config File - nginx.conf

nginx.conf

http {
    server {
        listen 80;
        server_name example.com;

        location /static/ {
            root /var/www/html;
            add_header Cache-Control "public, max-age=86400" always;
        }

        location /api/ {
            proxy_pass http://backend_server;
            add_header Cache-Control "no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0" always;
        }
    }
}

This configuration sets Cache-Control headers for two paths:

• /static/ serves static files with caching allowed for 86400 seconds (1 day).
• /api/ disables caching to ensure fresh data on every request.

The add_header directive adds the Cache-Control header to HTTP responses.

Commands

Check the nginx configuration file for syntax errors before applying changes.

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 Cache-Control header settings without stopping the server.

Terminal

sudo systemctl reload nginx

Expected Output

No output (command runs silently)

Check the HTTP headers for a static file to verify the Cache-Control header is set correctly.

Terminal

curl -I http://example.com/static/image.png

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: image/png

Cache-Control: public, max-age=86400

→

-I - Fetch only HTTP headers without the body

Check the HTTP headers for an API response to verify caching is disabled.

Terminal

curl -I http://example.com/api/data

Expected Output

HTTP/1.1 200 OK

Server: nginx

Content-Type: application/json

Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate, max-age=0

→

-I - Fetch only HTTP headers without the body

Key Concept

If you remember nothing else from Cache-Control headers, remember: they tell browsers and proxies how long to keep copies of your files to balance speed and freshness.

Common Mistakes

Forgetting to reload nginx after changing the configuration.

The new Cache-Control headers won't take effect until nginx reloads the config.

Always run 'sudo nginx -t' to test and then 'sudo systemctl reload nginx' to apply changes.

Setting Cache-Control headers globally without exceptions for dynamic content.

Dynamic pages might be cached and show outdated information to users.

Set different Cache-Control headers per location, disabling caching for dynamic API routes.

Using incorrect syntax in add_header directive.

Nginx will ignore invalid headers or fail to start if syntax is wrong.

Use quotes around the header value and verify with 'nginx -t' before reloading.

Summary

Use the add_header directive in nginx.conf to set Cache-Control headers per location.

Test configuration syntax with 'nginx -t' before reloading nginx to apply changes.

Verify headers with 'curl -I' to ensure caching behaves as expected.