nginx

Configure

INERTIA_STATIC_CDN=nginx
NGINX_CACHE_HOSTS=http://cache-1,http://cache-2   # default http://127.0.0.1; empty = headers-only
INERTIA_STATIC_REGISTRY=database                  # tag purges become URL purges

Server setup

Purging needs the ngx_cache_purge module (Alpine: apk add nginx-mod-http-cache-purge).

# nginx (OSS + ngx_cache_purge) configuration matching the "nginx" driver.
proxy_cache_path /var/cache/nginx/inertia levels=1:2 keys_zone=inertia:50m max_size=2g inactive=7d use_temp_path=off;

# Safety net: only store what the app marks as shared-cacheable
# (X-Inertia-Static-Cache: cacheable). Anything else is never stored.
# The purge target as sent (still percent-encoded), to match the cache key built from $request_uri.
map $request_uri $inertia_purge_target {
    "~^/purge(?<target>/[^?]*)" $target;
    default "";
}

map $upstream_http_x_inertia_static_cache $not_cacheable_by_app {
    default   1;
    cacheable 0;
}

server {
    listen 80;
    server_name example.com;

    location / {
        proxy_pass http://app:8000;
        proxy_set_header Host $host;

        proxy_cache inertia;
        proxy_cache_key "$scheme$host$request_uri";
        proxy_cache_methods GET HEAD;
        proxy_cache_revalidate on;                    # If-None-Match / 304 to the origin
        proxy_cache_lock on;                          # one origin hit per key
        proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
        proxy_cache_background_update on;             # stale-while-revalidate
        proxy_cache_bypass $http_authorization $cookie_inertia_static_preview;
        proxy_no_cache $http_authorization $not_cacheable_by_app $cookie_inertia_static_preview;

        add_header X-Cache-Status $upstream_cache_status always;
    }

    # GET /purge/blog/post  (the driver appends "*" for prefix purges)
    location ~ ^/purge(/.*)$ {
        allow 127.0.0.1;
        allow 10.0.0.0/8;
        allow 172.16.0.0/12;
        deny all;
        proxy_cache_purge inertia "$scheme$host$inertia_purge_target$is_args$args";
    }
}

The map + proxy_no_cache pair stores only responses marked cacheable by the package.

Purging

Method	Purges
purgeUrls()	the given pages (HTML and page JSON)
purgeTags()	every page with one of the tags (through the tag registry)
purgePrefix()	every page under the path
purgeAll()	every page of this app's hostname