Upgrade from Mautic 3.x to Mautic 4.4.11

It is not yet time to migrate to Mautic 5 for your production environment, it is still too soon!
Mautic 4 on the other hand is currently very mature. This is the most stable, efficient and secure Mautic version we had in a very long time, especially after the recent release of Mautic 4.4.11, which is the last release in the Mautic 4.x series.
If you haven’t yet updated your Mautic 3 to Mautic 4, now is the time, here’s a guide to do so, how to upgrade to Mautic 4 in 3 simple steps.

UPDATED on FEB 9 2024 for Mautic 4.4.11
This tutorial is built for and tested with Ubuntu 20.04, if you have a different Linux distribution or a different version of Ubuntu, some commands might be slightly different on your server or VPS.

We can follow these 4 simple steps to perform a secure Mautic 3 to Mautic 4 upgrade that won’t give you any unexpected surprises down the road:

1. Check the health of your Mautic database schema
2. Migrate from Mautic 3.x to Mautic 3.3.5
3. Prepare for the Mautic 4 requirements.
4. Migrate from M3.3.5 to Mautic 4.4.11

Step 1: Check the health of your Mautic database schema

First we need to migrate our M3 Mautic instance to the latest Mautic 3 version, that is: Mautic 3.3.5.

Let’s make sure you are root
sudo su

Let’s start safely by forcing proper permissions and clearing the cache
find /var/www/html -type d -exec chmod 755 -- {} +; find /var/www/html -type f -exec chmod 644 -- {} +; chown -R www-data:www-data /var/www/html

sudo -u www-data php /var/www/html/bin/console cache:clear

Let’s make sure your schema is updated, this step will tell you if you are ready to proceed with the migration.
First see if there is anything that requires migrating:

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

If you get zero results (no queries to run or up to date) you do not need to run the following 2 commands and can proceed directly with the upgrade.

If you do get some queries, and you know well your SQL, you can check what exactly is going to be done to your DB.
php /var/www/html/bin/console doctrine:schema:update --mysql-dump

WARNING: The next step can destroy your Mautic installation (did you make a backup of your DB?).

Finally, to execute all, the changes, you can run:
php /var/www/html/bin/console doctrine:schema:update --force

If you do not get any errors and the schema is updated, you are good to proceed.
If on the other hand, you do get some errors or warnings, you need to fix them before proceeding. If you decide to go ahead despite finding some errors, you might find yourself stranded in future updates or upgrades.

Step 2: Migrate from Mautic 3.x to Mautic 3.3.5

We can check which version are we suggested to upgrade to?
sudo -u www-data php /var/www/html/bin/console mautic:update:find

It should return something like:

Version 3.3.5 of Mautic is available for download. Please visit https://github.com/mautic/mautic/releases/tag/3.3.5 for more information.
To update, you can run:
sudo -u www-data php /var/www/html/bin/console mautic:update:apply

It will ask you:
Are you sure you wish to update Mautic to the latest version?
Type “y” and press enter.

The process will start

Step 5 [—–>———————-] Clearing the cache

Now we need to do a second pass to “finish” the upgrade to M3.3.5:
sudo -u www-data php /var/www/html/bin/console mautic:update:apply --finish

Step 3 [============================] Success! You are now running version 3.3.5 of Mautic.

You can now browse your Mautic instance and it should be upgraded to Mautic 3.3.5

Anyhow, we are going to run the schema updater once more…

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

The upgrade to the latest version of Mautic 3 is now complete.

Now we can start with the M3 to M4 Upgrade:

Step 3: Prepare for the Mautic 4 requirements.

We now need to prepare your server so it meets the Mautic 4 requirements.
Let’s first check your database version is MariaDB 10.3 or newer.
systemctl status mariadb

You should get a response similar to this:
● mariadb.service – MariaDB 10.3.38 database server
Loaded: loaded (/lib/systemd/system/mariadb.service; enabled; vendor preset: enabled)
Active: active (running) since Sat 2023-05-13 19:12:04 UTC; 1 day 3h ago

If it is 10.3.x or newer you are good to go.

You’re gonna need a newer PHP version, let’s upgrade to PHP 8.0!
apt install libapache2-mod-php8.0 php8.0 php8.0-xml php8.0-mysql php8.0-imap php8.0-zip php8.0-intl php8.0-curl php8.0-gd php8.0-mbstring php8.0-bcmath -y

And now we need to disable the old PHP 7.4 or 7.3 that you are currently running
a2dismod php7.3
a2dismod php7.4

And we also enable the newly installed PHP 8.0
a2enmod php8.0

Let’s make sure your CLI also has the proper version of PHP:
update-alternatives --set php /usr/bin/php8.0

Great, let’s make sure we did it right
pvp -v

Should return

PHP 8.0.28 (cli) (built: Feb 14 2023 18:32:57) ( NTS )
Copyright (c) The PHP Group
Zend Engine v4.0.28, Copyright (c) Zend Technologies
with Zend OPcache v8.0.28, Copyright (c), by Zend Technologies

And the last task is to restart the Apache server so the changes take effect
service apache2 restart

Step 4: Migrate from M3.3.5 to Mautic 4.4.11

Eager to migrate to M4? Just 3 more commands to go, we are ready to rumble!

Let’s see what update Mautic proposes:
sudo -u www-data php /var/www/html/bin/console mautic:update:find

Looks good, 4.4.11 is the latest, let’s apply the update:
sudo -u www-data php /var/www/html/bin/console mautic:update:apply

We need to apply a second time with an extra parameter “–finish”
sudo -u www-data php /var/www/html/bin/console mautic:update:apply --finish

That’s it, your Mautic should now be version 4.4.11