Mautic Update How-To: Don’t Click that Button!

Flawless Mautic upgrades every time! Not an impossible dream, just a simple step by step guide…
You might be already suffering the consequences of an incomplete Mautic update without knowing about it!
Just make sure you don’t click that button yet!!! There’s a better way…

A considerable percentage of Mautic support requests are from users having some kind of problem either when updating Mautic or right after doing so.
In general, Mautic updates are a trivial task that one must perform several times a year in order to keep Mautic up to date, however, there are several rules of thumb you should take into account when doing so.

Mautic updates are one of the most feared maintenance tasks among Mautic users, if you are not worried about upgrading your Mautic installation, you probably are doing it wrong, cause even if you don’t know it yet, you might be already suffering the consequences of a partial or incomplete update.
Despite the fanfare around each release, you shouldn’t hurry into new updates, upgrading Mautic can be a nerve-racking chore, especially for less-technical users. Before you hit “Update Now” in the dashboard, check these tips about how to safely and successfully upgrade your Mautic installation.

Stick with me to find out how healthy your Mautic installation is and sleep better after completing these steps. Let’s get started!

Pre-Update Steps

There are 2 recommended tasks that you should perform before you update Mautic, those are not required for the upgrade to run, however, if anything would go wrong, you’ll be very happy of having done so.

1. Delete your Mautic Cache
2. Backup your Mautic directory and Database.

Backing up your Mautic installation before every Mautic upgrade maximizes your chances of a trouble-free Mautic upgrade and if something fails, you can just recover from a failed Mautic upgrade and try again.

Step 0: Don’t click that button!

The simplest way to update your Mautic installation is certainly to click the big bright orange “Update Now” button that pops up right after each new Mautic release. Sadly it is also the most dangerous way to do so and the chances it will end in trouble are too big to ignore.
There are certain times when clicking that button is OK, but most of the time it just isn’t, so hear me out before you do.

If you already did click it and you got into some trouble afterward, don’t worry, we’ll try to solve that too in the next steps.

Even if your last update went perfectly OK (or so it would seem) there might be dangers lurking in the database that you didn’t know about, we’ll also try to find if there are any dark shadows hiding in your own DB.
So please be patient, and for now… Do not click that button!

We’re gonna be checking your Mautic installation’s health in a gifi…

Step 1: Choose wisely

Which version to update to? Latest? Probably not such a good idea…
Most mautic releases include new features and fix lots of bugs, and that’s why so many people are eager to jump to the latest version as soon as it is released, however, it’s not that obvious how Mautic releases work and most of all it’s not always easy to choose the right version for your needs.

Before you go ahead with your Mautic update, go to Github and review the existing issues, see if there’s any problem you might be running into.
Also check the “Download Mautic” section of this blog, besides providing you a no-forms easy way to Download Mautic, you will also find some information about how stable different Mautic versions are.

Anyway, here’s the basic rule of thumb:
Each Mautic releases ending in zero contain new features and hence some new bugs are usually introduced.
Releases ending in subsequent numbers focus on making Mautic more stable and fixing any bugs introduced in previous releases.

Step 2: Verify the health of your current version:

Chances are you are already running a “not-so-healthy” Mautic instance. If you ever did a “clicking the button” Mautic upgrade, the chances it didn’t fully complete are astonishingly high, even if the wizard completed successfully.

NOTE: If you don’t have access to an SSH console to issue these commands, you can try this tool to send the commands from your browser:
https://github.com/virgilwashere/mautic-cron-commands

So before we go for it, it’s a good idea to check the health of the Mautic database before proceeding with the update.

php /var/www/html/app/console doctrine:migration:migrate

This will check if there are any pending database migrations and if there are, it will perform the migration.

Now we’re gonna make sure there aren’t any differences between your database schema and how it is supposed to be:

php /var/www/html/app/console doctrine:schema:update --force

This will check if your schema is up to date and if not it will perform the required modifications.

Finally, clear the Mautic cache:

php /var/www/html/app/console cache:clear

Now go browse your Mautic UI to check if everything is running properly, also check the Mautic logs apache logs and PHP logs to see if there’s any new error.

Step 3: Install the Mautic update package YOU have chosen.

Most guides and the official documentation will invite you to upgrade to the latest version, but as previously explained, that might not be the best version for you, make sure you download the package that best suits your needs and then, instead of blindly running the latest version, upgrade to the version you have chosen, with:

php /var/www/html/app/console mautic:update:apply --update-package=/path/to/updatepackage.zip

Step 4: Repeat step 2

First we migrate:

php /var/www/html/app/console doctrine:migration:migrate

Then we check the database schema:

php /var/www/html/app/console doctrine:schema:update --force

And finally, clear the Mautic cache:

php /var/www/html/app/console cache:clear

Again, go browse your Mautic UI to check if everything is running properly, and check the Mautic logs, apache logs, and PHP logs to see if there’s any new error.

That’s it! your Mautic instance should now be healthy and updated, if anything did go wrong during this process or you have any questions, don’t hesitate to ask in the comments below, cheers and happy marketing!