This guide will tell you how to upgrade your Mautic 3+ installation to Mautic 4+. I have to say to smoothest upgrade ever. All command included and some heads up.

Mautic 4 is the most stable release I’ve seen in years, we are already using it by many customers at Friendly. At the beginning of this year, when we upgraded from Mautic 2 to Mautic 3, we had several issues with the database structure and even the file system. This time the upgrade ran really well. Here is a simple guide how we did it.

In this tutorial I will use sudo commands just to make sure you can run all commands, even if you don’t log in as a user, that is in the www-data group. I know this is not the proper way, but it will work for those who don’t want to lose themselves in the mysteries of user privileges of Linux.

My Mautic install lives in /var/www/html/mautic and I will use all commands respectively. The previous install was running in a php7.3 environment, we will need to upgrade that to php7.4 as well.

Click here for a quick video to see why Mautic 4 is so awesome!

Let’s begin:

Backup everything

We are using Linux Containers, so we can create snapshots with just one click and revert if the sh1t hits the fan. But if you don’t you should make backups:

Backup file system

Navigate out from the Mautic folder to /var/www/html

zip -r output_file.zip folder1

Backup your database

mysqldump -u [user name] –p [password] [mautic database_name] > [dumpfilename.sql]

You can check if the files are created by running:

ls -la

You should see a .sql and a .zip files in there.

Environmental update

Update your php7.3 to php7.4 if you haven’t done yet:

apt install mariadb-server apache2 libapache2-mod-php7.4 php7.4 unzip php7.4-xml php7.4-mysql php7.4-imap php7.4-zip php7.4-intl php7.4-curl php7.4-gd php7.4-mbstring php7.4-bcmath ntp -y

Let’s change all environmental variables:

sudo nano /etc/php/7.4/apache2/php.ini

You’ll need to change the followings:

file_uploads = On
allow_url_fopen = On
short_open_tag = On
memory_limit = 256M
upload_max_filesize = 100M
max_execution_time = 300
post_max_size = 64M

Regarding memory limit, you can be more generous and lift to 512M as well. Upload max filessize is also up to you. I suggest a minimum of 20MB.

Now move to php4 officially, and restart our Apache.

sudo a2enmod php7.4
sudo a2dismod php7.3
sudo systemctl restart apache2

Let’s check the version:

php -v

You supposed to see something like this:

PHP 7.4.23 (cli) (built: Aug 26 2021 15:51:37) ( NTS )
Copyright (c) The PHP Group
Zend Engine v3.4.0, Copyright (c) Zend Technologies
    with Zend OPcache v7.4.23, Copyright (c), by Zend Technologies

Get ready for the heart surgery. In order to do that we stop the heart: sStop the cronjobs from running.

sudo crontab -e

You can just add a # in front of the cron commands, like:

# * * * * * CRONJOBS HERE

Command line update

In order to create more tension we will do this in 2 steps. First we update to 3.3.4 and then to 4.0.1.

Let’s look for a new version:

cd /var/www/html/mautic
sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:find

The new version is found, let’s apply the update:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply

Now we are prompted to apply –finish. I would like to stop here for a moment. I know, that it is not the right way to use sudo when you are working here, but it is just simpler for folks if we don’t go into permissions. But using a root user during updates can cause file creation with the wrong ownership. In order to avoid it we will make sure by almost every step that the files belong to the right user. So we hand over the files to the www-data user all the time (which is running our we server.)

We do it by running this:

sudo chown -R www-data:www-data /var/www/html/mautic/
sudo chmod -R 755 /var/www/html/mautic/

And now we can finish:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply --finish

If everything went well, we are on the 3.3.4 version, half way to 4.0.1. Let’s look for a new version, and apply changes:

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:find
sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply

Make sure file ownership is okay:

sudo chown -R www-data:www-data /var/www/html/mautic/
sudo chmod -R 755 /var/www/html/mautic/

And now hit a home run (A golden goal if you are in Europe.)

sudo -u www-data php /var/www/html/mautic/bin/console mautic:update:apply --finish

Congratulations! You are now officially on Mautic 4.0.1.

Aftercare

You need to make sure your templates are okay. Make sure, that all of your email / landing page templates have the following config file format especially the red line:

{
  "name": "Template name",
  "author": "Mautic team",
  "authorUrl": "https://mautic.org",
  "builder": ["grapesjsbuilder"],
  "features": [
    "email"
  ]
}

If you are upgrading from a previous version, all your templates will have “builder”: “grapesjsbuilder”, format, and you really need those brackets now.