Page caching: document the warm origin, and that rendering and warming need different URLs

The file to edit is content/5.nuxt-module/11.page-caching.md, specifically the 'Warming the cache from site settings' section. Read the existing documentation to understand the current structure, then add the missing explanation about when and why to set NUXT_CWA_PAGE_CACHE_WARM_ORIGIN, focusing on single-server vs. Kubernetes deployments. Verify the Caddy certificate path mentioned in the issue against the project's volume layout. Ensure the two smaller corrections about the single-flight lock and failure list are also incorporated. Test by building the docs locally to confirm formatting is preserved.

From cwa-nuxt-module#343. The module change is diagnosis only — how the warm connects is unchanged — but the page-caching docs are missing the thing that makes a single-server deploy work at all.

Page: content/5.nuxt-module/11.page-caching.md, in Warming the cache from site settings. NUXT_CWA_PAGE_CACHE_WARM_ORIGIN is listed as an option, but not when you would set it — and on a single-server deploy it is mandatory, not an escape hatch.

The point to get across

origin defaults to the origin of apiUrl, and the public host still travels in the Host header, so the page is stored under the key visitors hit and the request never leaves the cluster.

On Kubernetes, leave it unset — Caddy there listens on port 80 with no HTTPS and no redirect, so the derived origin is already right.

On a single-server deploy, where Caddy runs its own automatic HTTPS, it must be set, and to a different URL from the one the server renders with. These are not the same request and they need different schemes:

Over plain HTTP on that stack, Caddy's automatic HTTPS answers every page with a 308, so every page is reported failed and nothing is warmed.

Worth stating explicitly: don't keep the warm on HTTP to dodge the certificate. Caddy's reverse_proxy sets X-Forwarded-Proto from the scheme it terminated, so pages would be rendered and cached with http:// canonical and og:url values no visitor ever receives — for the API's full cache lifetime.

Where Caddy issues the certificate itself (SERVER_NAME=localhost, a .local host, or tls internal) the warm fails with DEPTH_ZERO_SELF_SIGNED_CERT, because Node does not trust Caddy's own root. Point Node at it with NODE_EXTRA_CA_CERTS (Caddy writes the root to /data/caddy/pki/authorities/local/root.crt in its data volume) or --use-system-ca once it is installed in the system trust store. Local development hits the same wall against the self-signed certificate; set origin to a plain http:// URL there instead.

The module offers no way to turn certificate verification off, and won't — worth saying in the docs so nobody goes looking. It would be a permanent invisible downgrade in the only TLS client the module has, and it would make a misconfigured origin succeed quietly: pointed at the wrong host you would be told every page was warmed while nothing was stored.

Two smaller corrections on the same page

• The single-flight lock is per process: a second request to the same server gets a 409 while one is running, but separate replicas can warm at the same time. The admin message now says "on this server".
• The failure list now names the cause: a redirect shows where it was sent — /about (308 → https://www.example.com/about) — and an unreachable page shows the underlying error code — /about (no response: DEPTH_ZERO_SELF_SIGNED_CERT). Only a 200 counts as warmed; the page list already excludes redirect routes, so a 3xx here means the request never reached the renderer.

One thing to check before publishing

The /data/caddy/pki/authorities/local/root.crt path is Caddy's documented default but was not confirmed against the template's volume layout — worth a glance.

Background on why the obvious fix was rejected: the issue originally proposed setting servername for https origins. That is a no-op — Node's HTTP agent derives the TLS server name and the certificate identity check from the Host header when none is set, verified against a real TLS server with an SNICallback. The only real failure is certificate trust, which no module code can fix.