Maintain and update Heatlens

1. Backups and preparation
2. Ordered update procedure
3. Post-change checklist
4. Rollback
5. Tasks, retention and mail
6. Deactivation and uninstall
7. Capacity and monitoring

This guide is for the Matomo instance operator. Coderise supplies the plugin, documentation and support; the operator manages hosting, scheduling, backups and mail delivery.

Backups and preparation

Before changing anything, record versions, read the changelog and verify the ZIP. Back up the Matomo database, config/config.ini.php, Heatlens directory and deployment configuration together. Keep a copy outside the web-served directory.

Check that restoration is possible, preferably on an isolated copy. Avoid partial backups during writes or schema changes; follow your database administrator's consistent backup procedure. Disable mail delivery to real users on a production copy.

Rehearse changes in staging before deploying to your instance.

Ordered update procedure

1. Verify compatibility, package integrity, notes and backups. Keep the installed version's ZIP.
2. Deactivate Heatlens. Preserve the old directory outside plugins/ and outside the public web root.
3. Install the complete new directory. Do not overlay files and leave obsolete modules. Do not uninstall as an update step.
4. Reload the web PHP service serving Matomo (PHP-FPM or Apache), then reactivate, regenerate the tracker and clear caches as the web user.
5. Invalidate matomo.js or piwik.js caches/CDNs and reload Matomo in the browser.
6. Check the displayed version, campaigns and previous records, then perform the checklist below.

Linux example from the Matomo root, using www-data as the web user:

sudo -u www-data php console plugin:deactivate Heatlens

Replace the directory and reload web PHP using your hosting procedure, then:

sudo -u www-data php console plugin:activate Heatlens
sudo -u www-data php console custom-piwik-js:update
sudo -u www-data php console cache:clear

A CLI opcache_reset does not clear web PHP's OPcache. Reproducible ZIPs use fixed timestamps: relying only on file dates may leave old code in memory. Allow for the short interruption when reloading PHP.

Docker deployments

Update the persistent source chosen at installation: the host mount or image plus its volume strategy. A new image alone may not replace files in an existing volume. Verify the actual container path. With the example bind mount, deactivate before replacing the host directory, then:

docker compose restart matomo
docker compose exec -T -u www-data matomo php console plugin:activate Heatlens
docker compose exec -T -u www-data matomo php console custom-piwik-js:update
docker compose exec -T -u www-data matomo php console cache:clear

Adapt matomo to your PHP service. If the image or Compose changes, recreate the service through your deployment procedure instead of merely restarting it. Do not remove Matomo/database volumes to update the plugin.

Post-change checklist

• Correct version and activation, with no diagnostic error in Matomo.
• Ordinary Matomo tracking still works.
• Existing campaigns, counters and snapshot revisions remain readable with the correct filters.
• A dedicated campaign records nothing without consent, then a page and points after consent; withdrawal stops collection.
• Fictitious private text is masked; snapshot and JSON/PNG exports are readable.
• No new Heatlens errors in Matomo/PHP logs or the browser.
• Scheduler operational; notification tests only send to an authorized test mailbox.
• Under Docker, version and data survive a container recreation in staging.

Record date, versions, results and anomalies. The first recording checklist gives detailed steps.

Rollback

Deactivate, restore the previous plugin directory and reload web PHP. Restore the previous configuration if changed, reactivate and regenerate tracker/cache. Invalidate the CDN and repeat the checklist.

If the new release changed the schema, follow its notes: restoring a matching database backup may be necessary. That also replaces Matomo data written since the backup. The operator must plan that potential loss; copying old files is not a universal database rollback.

RC1 has no table migration relative to the tested commercial edition. No migration tool from the historical fork is supplied.

Tasks, retention and mail

Heatlens registers daily purge and hourly processLifecycle with Matomo's scheduler. The operator configures and monitors scheduling using the Matomo archiving guide. Declared frequency does not guarantee execution when the scheduler is not running.

For a controlled intervention after backup, these commands execute Heatlens tasks. They are not read-only diagnostics: purge deletes expired data; processLifecycle may send notifications and create a repeat campaign.

sudo -u www-data php console scheduled-tasks:run 'Piwik\Plugins\Heatlens\Tasks.processLifecycle'
sudo -u www-data php console scheduled-tasks:run 'Piwik\Plugins\Heatlens\Tasks.purge'

Use them for a controlled acceptance test, not as a second cron without reviewing Matomo's existing scheduling. Check exit status, logs and expected effects on test fixtures.

Retention: 0 adds no campaign-specific lifetime; Matomo log deletion still applies. A value from 1 to 3650 days adds a purge policy. Historical quota counters do not decrease after deletion. Shared snapshots are conservatively removed during visitor erasure.

Notifications require the user's personal preference, permissions and working Matomo mail transport. Repetition creates a new campaign after its configured interval when the completed campaign remains active; it does not reset the old campaign's history.

Deactivation and uninstall

Deactivating and regenerating the tracker stops collection while preserving data. Purge tracker delivery caches too.

In RC1, Matomo uninstall removes plugin files/settings but does not automatically drop the five Heatlens tables. To erase campaigns, use their delete action while the plugin is still active. Deletion is permanent.

For complete removal, the database administrator identifies the actual prefix and these five tables after backup and stopping collection: heatlens_batch, heatlens_page, heatlens_snapshot, heatlens_notification, heatlens_campaign. Do not delete other tables or use wildcard deletion. This guide supplies no automatic DROP TABLE command.

Capacity and monitoring

Start with a few pages and appropriate sampling/caps/retention, then measure storage and collection/report latency. CI recorded 1600 pages across 20 synthetic sites and verified a cap of 10 for 80 concurrent attempts; this is not a production throughput guarantee. Long/complex pages and campaign count influence requirements.

Monitor errors, database growth, scheduler runs and tracker caches. Follow troubleshooting and provide anonymized evidence when needed.