Skip to content

caching.md

Latest commit

 

History

History
490 lines (334 loc) · 15.3 KB

caching.md

File metadata and controls

490 lines (334 loc) · 15.3 KB
Raw

Caching

SlickStack uses several independent cache layers to reduce repeated PHP execution, database work, filesystem lookups, and origin requests. Each layer stores different data and has a different purge method.

Purging one layer does not automatically clear the others unless a broader SlickStack workflow explicitly invokes every purge script.

Table of Contents

Cache layers

Layer What it caches Main location Purge command
Nginx FastCGI cache Complete HTTP responses generated by PHP /var/www/cache/nginx/ sudo bash /var/www/ss-purge-nginx
PHP OPcache Compiled PHP bytecode PHP-FPM shared memory and /var/www/cache/opcache/ sudo bash /var/www/ss-purge-opcache
Memcached WordPress objects and cached transients Local memory on 127.0.0.1:11211 sudo bash /var/www/ss-purge-memcached
WordPress transients Temporary application values stored in the database when not served from persistent object cache Production WordPress options table sudo bash /var/www/ss-purge-transients
Nginx open-file cache Filesystem lookup and metadata results Nginx worker memory No dedicated SlickStack purge command
Browser cache Static assets already stored by visitors' browsers Visitor devices Controlled through HTTP response headers
Cloudflare cache Responses and assets cached at Cloudflare's edge Cloudflare network Managed separately in Cloudflare

See Nginx, PHP-FPM, Memcached, WordPress, and Cloudflare for the underlying services.

Purge commands

Clear every SlickStack-managed application cache layer with:

ss purge

The alias runs these scripts in order:

sudo bash /var/www/ss-purge-opcache
sudo bash /var/www/ss-purge-memcached
sudo bash /var/www/ss-purge-nginx
sudo bash /var/www/ss-purge-transients

Individual aliases are also available:

ss purge nginx
ss purge opcache
ss purge memcached
ss purge transients

Purging during a traffic spike can sharply increase PHP, MySQL, disk, and network work while caches rebuild. Prefer targeted purges when only one layer is stale.

Nginx FastCGI cache

The main Nginx configuration stores FastCGI responses under:

/var/www/cache/nginx/

The cache zone is named WORDPRESS. Its key includes:

scheme + request method + host + full request URI + WooCommerce session value

The standard behavior includes:

  • cache locking to reduce duplicate upstream work
  • background cache updates
  • revalidation
  • serving stale responses during selected upstream errors and timeouts
  • a configurable inactive period and maximum disk size
  • caching eligible 200, 301, and 404 responses

The current Nginx template ignores upstream Cache-Control, Expires, and Set-Cookie headers for FastCGI cache decisions. Correct route, request, and cookie bypass rules are therefore especially important.

Default FastCGI settings

The current ss-config defaults are:

FCGI_CACHE="true"
FCGI_CACHE_VALID="360m"
FCGI_CACHE_INACTIVE="1440m"
FCGI_CACHE_MEMORY="256m"
FCGI_CACHE_MAX_SIZE="4096m"
FCGI_CACHE_TMPFS="false"

Additional settings control FastCGI timeouts and response buffers.

After changing these values, run:

sudo bash /var/www/ss-install

SlickStack generates Nginx configuration from ss-config; changing the variable alone does not rewrite the active files.

Cache bypass rules

The production server block begins with caching enabled when:

FCGI_CACHE="true"

It bypasses FastCGI cache for important dynamic requests, including:

  • POST requests
  • requests containing query strings
  • WooCommerce AJAX requests
  • sensitive paths such as account, cart, checkout, login, order, profile, registration, settings, and WordPress administration
  • logged-in WordPress users
  • password-protected content
  • WooCommerce carts and sessions
  • recent commenters
  • REST API requests under /wp-json/

These rules are pattern-based. A custom plugin, localized route, membership area, API endpoint, or commerce workflow can require an additional bypass rule.

When:

FCGI_CACHE="false"

SlickStack generates the server block with its default skip-cache value set to 1, which disables FastCGI caching for normal PHP responses.

Purging Nginx cache

Run:

sudo bash /var/www/ss-purge-nginx

The script:

  1. touches its SlickStack timestamp file
  2. removes the contents under /var/www/cache/nginx/
  3. reloads Nginx

It does not clear:

  • PHP OPcache
  • Memcached
  • WordPress transients
  • browser-held assets
  • Cloudflare edge cache

Check the cache directory with:

sudo du -sh /var/www/cache/nginx
sudo find /var/www/cache/nginx -type f | wc -l

A cache directory rebuilding after the purge is normal.

Nginx open-file and browser caching

Nginx also enables open_file_cache, which caches filesystem metadata inside Nginx workers. It is separate from FastCGI response caching and uses these ss-config settings:

OPEN_FILE_CACHE_MAX="10000"
OPEN_FILE_CACHE_MIN_USES="2"
OPEN_FILE_CACHE_VALID="2m"
OPEN_FILE_CACHE_INACTIVE="5m"
OPEN_FILE_CACHE_ERRORS="on"

Production static-file locations also send long browser cache lifetimes for many assets. Clearing the origin FastCGI directory cannot force a visitor's browser to discard a previously stored CSS, JavaScript, font, image, or other static file.

Use versioned asset URLs or changed filenames for reliable static-asset invalidation rather than expecting a server-side purge to reach every browser.

PHP OPcache

OPcache stores compiled PHP bytecode so PHP does not need to parse and compile the same scripts on every request.

The PHP 8.3 template enables:

opcache.enable=1
opcache.enable_cli=1
opcache.validate_timestamps=1
opcache.revalidate_freq=2
opcache.file_cache=/var/www/cache/opcache
opcache.file_cache_only=0

Timestamp validation normally allows changed PHP files to become visible without a manual purge after the configured revalidation delay. The disk file cache is a fallback in addition to the normal in-memory cache.

Purging OPcache

Run:

sudo bash /var/www/ss-purge-opcache

The current script attempts three actions:

  1. runs opcache_reset() through WP-CLI
  2. creates a temporary random PHP file and requests it over HTTPS as a PHP-FPM fallback
  3. removes physical files under /var/www/cache/opcache/

The WP-CLI call runs under PHP's CLI SAPI and should not by itself be treated as proof that PHP-FPM's in-memory cache was reset.

Current web-fallback limitation

The fallback creates a random root-level file such as:

/var/www/html/purge-RANDOM.php

The current production Nginx PHP allowlist accepts only specific WordPress PHP entry points and returns status 444 for other PHP files. The random purge filename does not match that allowlist, so the request can be rejected before reaching PHP-FPM.

The script still removes the disk file-cache contents. A PHP-FPM restart also recreates its in-memory OPcache state:

ss restart php

A full ss-install purges OPcache and subsequently restarts PHP-FPM.

Memcached object cache

SlickStack uses a loopback-only Memcached service for persistent WordPress object caching when:

WP_OBJECT_CACHE="true"

The managed production drop-in is:

/var/www/html/wp-content/object-cache.php

Staging and development do not receive this managed drop-in. Memcached is separate from Nginx page cache and OPcache.

Purging Memcached

Run:

sudo bash /var/www/ss-purge-memcached

The script sends flush_all to 127.0.0.1:11211 and runs memcflush. This clears the entire local instance, including ordinary WordPress objects and transients currently stored there.

Useful checks include:

systemctl status memcached
sudo ss -lntp | grep 11211
printf "stats\r\nquit\r\n" | nc 127.0.0.1 11211

Restarting Memcached also discards all in-memory entries:

ss restart memcached

See Memcached for service configuration and WordPress integration.

WordPress transients

WordPress transients are temporary application values. Without a persistent object cache, they are commonly stored in the WordPress options table. With Memcached active, many transient values can instead live in Memcached.

Run:

sudo bash /var/www/ss-purge-transients

The script directly runs this type of match against the configured production options table:

LIKE '%_transient_%'

It is intended to remove ordinary transient values, timeout rows, and matching site-transient rows from the primary options table.

Current SQL-pattern limitation

The underscores in the current LIKE pattern are not escaped. In SQL pattern matching, _ means any single character rather than a literal underscore.

The query can therefore match option names more broadly than the intended literal _transient_ substring. This is another reason to treat the purge as a targeted maintenance operation rather than a harmless read-only check.

Other current boundaries:

  • it targets the configured production database only
  • it does not clear Memcached
  • it does not purge Nginx or OPcache
  • it does not iterate through every options table in a WordPress Multisite network
  • it uses a direct SQL deletion rather than WordPress APIs

When persistent object caching is active, purge Memcached as well when the goal is to remove every cached transient value:

ss purge memcached
ss purge transients

or use:

ss purge

Scheduled purges

Only Memcached and database transients currently expose recurring purge settings in ss-config:

INTERVAL_SS_PURGE_MEMCACHED="half-monthly"
INTERVAL_SS_PURGE_TRANSIENTS="monthly"

Supported Memcached intervals are:

half-weekly
weekly
half-monthly
monthly
never

Supported transient intervals are:

weekly
half-monthly
monthly
sometimes
never

The fixed wrapper schedules are:

Interval Actual schedule
half-weekly Every three days at 00:00
weekly Sunday at 00:00
half-monthly The 13th of each month at 00:00
monthly The first day of each month at 00:00
sometimes The first day of every second month at 00:00
never Disabled

There are no corresponding INTERVAL_SS_PURGE_NGINX or INTERVAL_SS_PURGE_OPCACHE settings in the current configuration.

See Cron Jobs before changing recurring tasks.

Full installation behavior

Near the end of every full ss-install, SlickStack:

  1. disables maintenance mode, which itself purges the Nginx cache
  2. explicitly purges the Nginx FastCGI cache again
  3. purges OPcache
  4. purges Memcached
  5. deletes production database transients
  6. restarts PHP-FPM, Nginx, Memcached, and MySQL

Therefore, rerunning ss-install is a much broader operation than clearing stale cache. Use an individual purge command when reinstallation is unnecessary.

Cloudflare and browser cache

Cloudflare edge caching is outside the four SlickStack purge scripts. A response can remain stale at Cloudflare even after every origin cache is empty.

Likewise, browser caching can preserve static resources after Nginx, PHP, and WordPress caches are cleared.

When diagnosing stale content, distinguish:

  1. browser cache
  2. Cloudflare edge cache
  3. Nginx FastCGI cache
  4. Memcached object cache
  5. WordPress transients
  6. PHP OPcache
  7. the authoritative WordPress database and files

Check Cloudflare response headers and purge the appropriate Cloudflare cache separately when the edge is involved. See Cloudflare.

Troubleshooting

A page remains stale

Check in this order:

ss purge nginx
ss purge memcached
ss purge transients

Then bypass or clear Cloudflare and browser cache. Purge OPcache only when the stale result appears related to changed PHP code rather than stored page or object data.

Logged-in or commerce pages appear cached

Review the request URI, method, query string, WordPress cookies, WooCommerce cookies, and custom application routes. The existing bypass rules cannot anticipate every plugin or localization.

Do not disable all caching before identifying which route or cookie is missing from the bypass policy.

PHP code changes do not appear

Check:

ss purge opcache
ss restart php
sudo tail -n 100 /var/www/logs/php-error.log
journalctl -u 'php*-fpm.service' --no-pager -n 100

Also verify that the edited file is the active file and was not replaced by a managed SlickStack installation workflow.

Memcached purge appears ineffective

Check the service, listener, PHP extension, and WordPress drop-in:

systemctl status memcached
sudo ss -lntp | grep 11211
php -m | grep -i memcached
ls -l /var/www/html/wp-content/object-cache.php

An application plugin can also maintain its own cache outside SlickStack's standard layers.

Load spikes after purging

A purge removes warm data and forces new PHP execution, database queries, object generation, and cache writes. Avoid repeated full purges during high traffic. Confirm the affected layer and clear only that layer.

Purge timestamps are recent but content is stale

SlickStack purge scripts touch their timestamps before performing their cache actions. A recent timestamp records that the script started; it does not prove that every command succeeded.

Inspect service state, cache paths, logs, and the public response instead of relying only on timestamps.

Managed-file boundaries

SlickStack manages:

  • Nginx cache paths and generated FastCGI settings
  • cache-bypass rules in managed server blocks
  • PHP OPcache configuration and file-cache path
  • the local Memcached service and production object-cache drop-in
  • purge scripts and their Bash aliases
  • recurring Memcached and transient purge hooks

Direct edits to generated Nginx, PHP, Memcached, WordPress, cron, and purge files can be replaced by ss-check, ss-worker, scheduled self-healing, or ss-install.

Persistent cache-policy changes require an existing ss-config option, an approved Nginx include where applicable, a custom cron file, a source-level SlickStack change, or configuration in the external cache provider.

Scope

The standard SlickStack caching model assumes:

  • one production WordPress application
  • one local Nginx FastCGI cache
  • one PHP-FPM OPcache
  • one loopback-only Memcached instance
  • one managed production object-cache drop-in
  • Cloudflare and browser caching managed separately

Redis, Varnish, LiteSpeed Cache, remote Memcached, cache clustering, per-site Memcached instances, CDN cache APIs, tag-based invalidation, cache warming, fragment caching, and centralized cache observability are outside the standard managed implementation.

Related guides