Mautic Plugin Production Installation Checklist for Teams

Why I am publishing this checklist now

A plugin install can change application code, cached configuration, runtime bytecode, scheduled work, and database state. Successful extraction does not establish readiness for a live instance.

This September 7 checklist records the operating standard I would use today: documentation first, staging second, and production only after a recovery rehearsal. Repeat the evidence check on install day because publisher instructions and package boundaries change.

Record compatibility for the exact target

Record the current and proposed Mautic releases, PHP versions used by the command line and web runtime, the database engine and version, the plugin release, and declared dependency constraints.

Separate what the publisher declares, what package metadata permits, and what your team has tested on a representative staging copy. A major-version statement does not replace testing your exact combination. Use the compatibility evidence under Related for a deeper review.

• Save the publisher page, package release, and retrieval date.
• List the user paths, commands, jobs, events, and integrations the plugin affects.
• Mark undocumented combinations as unknown until staging resolves the decision.

Write the cache and PHP-FPM sequence in advance

Identify the Mautic root, production cache path, user that should own generated files, and PHP service handling web requests. Command-line PHP and PHP-FPM can differ, so verify both.

Put each action in order: deploy files, set ownership, remove stale production cache when required, warm the cache as the correct user, restart the deployment’s PHP-FPM or equivalent runtime to clear OPcache, then inspect logs. Use that server’s service name.

Treat migrations and version bumps as a separate gate

Before any plugin-discovery or reload command, read the release notes and inspect whether the new package adds migrations or changes its stored version. Take a database backup before a command that may change schema or data, and know how long the application can remain in maintenance mode.

In staging, capture the reload command’s complete output, database errors, application logs, and the plugin version shown after the process. Verify the workflows in your inventory, not merely the presence of a menu item. If a migration stops, preserve its output and assess the database state before retrying; repeated commands are not a diagnosis.

Design rollback before copying files

A useful rollback plan names a trigger, an operator, and a recovery path for each state that can change. Keep the prior plugin files, a pre-change database backup, and a copy of any plugin-owned upload or storage directory. Confirm that those backups are readable and that the restore procedure has worked in staging.

File recovery and database recovery are different operations. Restoring an earlier plugin directory after a migration can leave old code facing a newer schema. Decide before the window whether recovery means restoring the full pre-change state, applying a publisher-documented reverse migration, or abandoning the rollout and restoring the staged backup.

• Define stop conditions such as a failed migration, broken login, job failure, or corrupt plugin workflow.
• Record who makes the rollback decision and how users will be kept out during recovery.
• Re-run the same functional checks after recovery and retain the logs with the change record.

Ask who owns the data after uninstall

Installation approval should include the exit path. Determine whether disabling or removing the plugin retains or deletes its database tables, configuration, uploaded files, logs, and exportable records. Check whether the publisher documents an uninstall command, an uninstall hook, a manual cleanup sequence, or a supported export.

Silence is not a retention policy. When removal behavior is undocumented, label it unknown, preserve the database and plugin-owned files, and test removal on a copy before touching production. Data ownership is operational only when the team can identify where records live, export what it needs, and recover them independently of the plugin’s user interface.

Worked example: applying the list to Deal Flow

On September 7, I applied this checklist to the current Deal Flow install and uninstall documentation. It directs an operator to extract the served archive under the Mautic plugins directory, back up the database before plugin reload, rebuild the cache, restart the PHP runtime, and verify both product screens and logs.

The same documentation draws an important recovery boundary: its rollback command restores plugin files but does not reverse database migrations. It also labels the outcome for database tables and uploaded files after removal as unknown. For this worked example, the production runbook therefore needs separate backups for the database, plugin files, and uploads, plus a staged recovery test before approval.

That result is not a universal description of Mautic plugins. It demonstrates the method: read one publisher’s current evidence, preserve every unknown, and convert each documented boundary into a concrete deployment or recovery step.

Frequently asked questions

What should be checked before installing a Mautic plugin in production?

Record the exact Mautic, PHP, database, and plugin versions; verify the publisher’s current compatibility statement; rehearse the install in staging; and prepare separate recovery paths for files, the database, and plugin-owned data.

Why restart PHP-FPM after rebuilding the Mautic cache?

A cache rebuild refreshes application configuration; a deployment-specific PHP-FPM or runtime restart clears old OPcache bytecode. Use the service name and operating user defined by your environment.

Does restoring earlier plugin files reverse database migrations?

No. Restoring files does not by itself reverse schema or data changes. Treat file rollback and database recovery as separate steps, then verify both paths in staging.

What should an operator know before uninstalling a Mautic plugin?

Determine what the removal process does to database tables, uploaded files, settings, and exports. If the documentation is silent, label the outcome unknown and preserve the database and plugin-owned files before removal.