The static cache #

This page is for IT teams in public bodies who are asked to "turn on the static cache", often because an older guide recommended it. It answers what the static cache is, why it ships off, when it can still make sense for a public body, and how to generate, serve and remove it. The sources are Static cache generator and the hosting page Static cache.

Contents #

1. What it is
2. Why it ships off
3. When it may still fit
4. Generating and checking it
5. Serving it and switching it off
6. Checklist

What it is #

The static cache turns public pages into plain files under var/<site>/static that the web server sends without starting Exponential. The rewrite rules answer from a file only for a plain GET or HEAD without a query string and without a session; forms, searches and signed-in users always get the live page.

Why it ships off #

site.ini [ContentSettings] StaticCache=disabled is the shipped value, and the installer writes it so. The installation book says: "Leave the static cache off." With it on, every publish regenerated the affected pages on every public siteaccess over HTTP inside the editor's request, so publishing became slow; Velocity's response cache gives visitors the same benefit without that cost (10.12 Performance tuning).

From Static cache; the other two are on Velocity response cache and HTTP cache.

When it may still fit #

The feature page describes it as suited to "sites with mostly public, rarely changing pages". For a public body that can mean:

• a small information site served by Apache or nginx where Velocity and the HTTP cache are not available;
• an emergency or crisis information site that must keep answering under a sudden surge, where a few seconds of extra publish time are acceptable.

Agree the publish cost with the editors first. With [CacheSettings] CronjobCacheClear=enabled the staticcache_cleanup cronjob part does the clearing instead of the publish.

Generating and checking it #

See what it would do first:

php bin/php/cache.php static status --allow-root-user

Expected: a list of the sites that can be generated and a line such as the static cache is not enabled in site.ini [ContentSettings] StaticCache; 3 sites can be generated. Only siteaccesses that need no login are offered. Generate one site, limited so you can see it work:

php bin/php/makestaticcache.php --site=site --max-pages=500 --max-depth=6 --allow-root-user

The same is in the administration under Setup > Cache management, section Static content cache, with a Stop button (Operating a site).

Serving it and switching it off #

To make the web server answer from the files, set StaticCache=enabled in settings/override/site.ini.append.php, block [ContentSettings], clear the INI cache and check that the web server rules of your installation are active:

php bin/php/ezcache.php --clear-tag=ini --allow-root-user

To go back, set it to disabled, clear the INI cache again, and remove the generated files:

php bin/php/cache.php static clear --allow-root-user

Pages served from files bypass the application, so they are not in Exponential's request logs. Keep that in mind for statistics and investigations.

Checklist #

• To do: The default (off) is kept unless a documented reason applies.
• To do: If on: editors accept the publish cost, or CronjobCacheClear is enabled.
• To do: cache.php static status shows the expected sites and page counts.
• To do: The procedure to switch it off and clear the files is in your runbook.

Related pages #

• Availability index of this folder
• Cache warming after changes
• Caching layers
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.