OCMLABS/MODULE-CLOUDFLARE · INSTALLATION

Installing the Cloudflare module, creating the API token and connecting your zone

Requirements

Magento Open Source or Adobe Commerce 2.4.4 or later
PHP 8.1 or later
A Cloudflare zone proxying the storefront (the orange cloud is on for the storefront hostnames)
A working Magento cron, so the purge queue consumer and the hourly health checks run

Install via Composer

composer require ocmlabs/module-cloudflare
bin/magento module:enable OCMLabs_Cloudflare
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:clean

In production mode also run bin/magento setup:static-content:deploy.

NOTE /

Run a full bin/magento cache:clean after installing or upgrading, not only a flush of the full page cache. The module registers plugins and a RequireJS map, and both stay stale until the config and layout caches are cleaned.

Verify the installation

bin/magento module:status OCMLabs_Cloudflare

In the admin, System > Cloudflare > Dashboard should appear. Nothing changes on the storefront yet: the module is disabled by default and edge caching is a separate switch.

Create the API token

In Cloudflare go to My Profile > API Tokens > Create Token > Create Custom Token for a user-owned token, or Manage Account > Account API Tokens for an account-owned token. Both work; the module verifies each kind at the right endpoint. Give it these permissions, scoped to the zones the store uses:

Permission	What the module uses it for
`Zone:Read`	Look up the zone, its plan and development mode
`Zone:Cache Purge`	Purge by tag, URL, prefix or everything
`Zone:Settings:Read`	Health checks on zone settings (SSL mode, Rocket Loader and so on)
`Zone:Settings:Edit`	Turn development mode on and off
`Zone:Cache Rules:Edit`	Apply the recommended cache rules. This is separate from Settings:Edit
`Analytics:Read`	The Analytics tab

Zone:Cache Rules:Edit is the one people miss. Without it everything works except applying rules; you can paste the rules by hand instead, as described on the Cache Rules page.

Connect the store

Everything lives under Stores > Configuration > OCMLabs > Cloudflare.

General (default scope): set Enable Cloudflare Integration to Yes and paste the API token. Account ID is optional and is detected from the token. Tokens created or rolled since 2026 carry a prefix and checksum (cfut_... user-owned, cfat_... account-owned) and are longer than the older 40-character form; paste the whole string. Click Test Connection.
Zone (website scope): switch the scope to each website and click Detect Zone, or paste the Zone ID. Each website can map to its own zone, and the API token can be overridden per website if a website lives on a different Cloudflare account.
Storefront Hosts is optional. Leave it blank and the hosts come from the website’s base URLs. Fill it in, one host per line, if the public host differs.
Storefront Origin is optional. It is only used by the “Origin sends edge cache headers” health check, which fetches a page straight from your origin. Use a host, host:port, an IP or a URL, for example https://203.0.113.7 or origin.example.com:8443.

The full field reference is on the System Settings page.

Start the purge queue consumer

Purges are queued by default and sent by the ocmlabsCloudflarePurge consumer on Magento’s built-in db queue connection. No RabbitMQ is needed, but the consumer has to run or tags pile up in the queue and Cloudflare keeps serving stale pages.

Option 1: Magento cron (default). If app/etc/env.php has no cron_consumers_runner key, Magento’s cron starts every registered consumer, including this one. To scope it explicitly:

'cron_consumers_runner' => [
    'cron_run' => true,
    'max_messages' => 10000,
    'consumers' => ['ocmlabsCloudflarePurge'],
],

Option 2: process supervisor. Run it as a long-lived process under supervisord or similar:

bin/magento queue:consumers:start ocmlabsCloudflarePurge --max-messages=10000

The “Purge queue consumer” health check tells you whether purges are going out.

Apply the cache rules and turn on edge caching

Open System > Cloudflare > Dashboard > Health and click Apply recommended cache rules, or run bin/magento ocmlabs:cloudflare:rules:apply. You see the diff before anything is written.
Under Stores > Configuration > OCMLabs > Cloudflare > Edge Cache (website scope), set Enable Edge Caching of HTML to Yes.
Click Run checks now on the Health tab. The live probes fetch a category page, the login page and a varied page through Cloudflare and report what the edge did.

To check by hand:

curl -sI https://www.example.com/some-category.html | grep -i cf-cache-status
curl -sI https://www.example.com/customer/account/login/ | grep -i cf-cache-status

The first should show HIT from the second request onward. The second should show DYNAMIC or BYPASS.

Grant admin access

The module registers these ACL resources under System > Permissions > User Roles:

OCMLabs_Cloudflare::dashboard - open the dashboard (Overview, Analytics and Health tabs)
OCMLabs_Cloudflare::purge - purge from the dashboard (quick purge, purge everything)
OCMLabs_Cloudflare::settings_write - change zone settings from the dashboard (development mode, apply cache rules, apply a health check fix)
OCMLabs_Cloudflare::purge_log - view the purge log
OCMLabs_Cloudflare::config - change module configuration under Stores > Configuration

Behind Varnish

If Varnish sits between Magento and Cloudflare, Magento’s stock VCL strips the headers the edge needs. Export the Cloudflare-aware VCL and load it instead, as described on the Varnish page. If you would rather not change your VCL, leave edge caching off. Purging, analytics, rules and health checks still work.