Cache Manager for CloudPanel

WordPress public-page caching, content invalidation and diagnostics for an operator-managed CloudPanel server. Requires the matching server integration in CloudPanel Companion.

The WordPress integration and operator-owned Varnish configuration form one cache contract. Installing a plugin alone cannot protect requests that Varnish serves without executing WordPress. Existing CloudPanel controller behaviour must be qualified alongside this policy before enabling either on a real site.

Current implementation

server/cache-policy.vcl defines a conservative public HTML policy. It requires an application opt-in, respects private response headers and cookies, bypasses all cookie-bearing and query-string requests, and disables stale delivery. It does not strip cookies, remove security headers or flush an object cache.

The companion supplies a backend and a per-host cache_manager_for_cloudpanel_revision subroutine. The separate loopback control endpoint authenticates each site's purge credential; direct Varnish PURGE is rejected. Invalidation changes an exact host's cache revision. Each request captures that revision before lookup, so a render started before an edit remains in the old namespace even if it finishes afterwards. Other hosts retain their caches. Selective purges are explicitly rejected in this initial version. Every relevant content edit refreshes the site's public HTML cache; this favours simple freshness over retaining unrelated cached pages.

The VCL uses stock Varnish without optional VMODs. The controller validates and activates a new configuration on a successful purge. A policy load changes its namespace; old objects expire normally, with a maximum configured lifetime of five minutes. The revision boundary is a successful purge acknowledgement, not the beginning of a WordPress database transaction. Failed purges remain queued and visible in administration; do not claim immediate freshness during an invalidation outage.

WordPress persistence hooks, a revision-checked retry queue, and a native Tools screen cover supported content changes, metadata, terms, menus, widgets, theme changes and WooCommerce product/variation changes. The integration has been tested with real product price, stock, variation, category and removed-term changes, private B2B sessions, independent populated carts and checkout. No real order or payment is required by the test suite.

The companion's tests/cache_integration.py runs real Varnish and the actual revision controller in isolated loopback processes. It covers privacy, cross-site credential isolation, range responses, old in-flight responses and concurrent purges.

Operator setup and controls

Use the companion's reviewed install-cache.py after installing its shared runtime. Save the generated integration through CloudPanel's native Vhost template so normal PHP-setting saves retain it. Native CloudPanel's PHP cache controller must be disabled in that owned template; the two controllers must not compete. The installer verifies the site identity, installs new plugin files atomically as the website owner, and refuses to overwrite different installed plugin code. Replaying an unchanged installation preserves credentials.

In WordPress, open Tools → CloudPanel cache for readiness, queued-purge errors, manual local purge and object-cache diagnostics. A dedicated Redis service can be connected with the companion's install-object-cache.py; enable/disable controls remain with the maintained Redis Object Cache provider. Existing foreign drop-ins are preserved. Redis is the qualified integration; Memcached extension detection does not silently install or replace a provider.

Only public HTML with an explicit application opt-in is cached, for at most five minutes. Cookie-bearing, authenticated, query-string, cart, checkout, account, JSON and private/no-store responses bypass. A missing or stopped controller removes cache readiness; Nginx falls back to uncached PHP. Actual controller interruption, native settings saves and server reboot have been checked.

Changes, deactivation and removal

Ship plugin code and the server policy as a matched release in a planned window. The provisioning installer deliberately refuses an unreviewed overwrite of an installed different version. Do not use the staging picker for cache infrastructure. Keep a recovery copy and pause new requests before replacing active code, drain existing PHP work, then verify an uncached rendered page and freshness before resuming traffic. Native vhost changes belong in the saved template.

Normal plugin deactivation first requires an acknowledged invalidation. A failed purge refuses deactivation and retains retry handling. If retiring the server integration, first route the site directly to uncached PHP through its native template, then disable the integration constant and deactivate the plugin. Keep server include files until the native template no longer references them. Do not force removal by changing the active-plugin database entry.

Cloudflare remains a separate cache layer. This plugin does not change Cloudflare settings or purge its edge cache. Multisite and automatic Memcached provisioning are not supported by this release. Configuration changes in unrelated plugins may need an explicit local purge or a plugin-specific invalidation hook.

References

• CloudPanel PHP controller
• Varnish invalidation
• WordPress object-cache loading

No customer data or credentials belong in this repository.