Upgrading Mautic from v2 to v3

A new client recently asked to upgrade a still functioning Mautic 2.15.3 running on Ubuntu 18.04 to the latest Mautic v3.

In this guide, we will look at how this can be achieved and what to look out for.

If you are running Mautic on a VPS or in a LXC/LXD container, it is highly recommended to take a snapshot before starting the upgrade process. This way you can always roll back to the old version if something goes wrong.

We assume here that you are logged in as root and do not have to use “sudo” every time a command needs to be executed.If you are not yet root, switch now.

# sudo -i

Make sure the system is up-to-date and that all packages are fully upgraded.

# apt update && apt upgrade -y

Create an alias “mtc” that replaces the long command “sudo -Hu www-data php /var/www/mautic/app/console” so we don’t have to enter it in full each time. If your mautic root directory is not “/var/www/mautic” modify it accordingly.

# vi .bashrc

Add at the end.

alias mtc='sudo -Hu www-data php /var/www/mautic/app/console'

Implement new settings.

# exec bash

Check if the alias is working.

# mtc --version

Which should give you the current version of Mautic.

Mautic version 2.15.3 - app/prod

Even if you have taken a snapshot, it is always advisable to take a dump of the database before starting the upgrade.

# mysqldump mautic > mautic-$(date +"%m-%d-%y").sql

Prepare the upgrade.

# mtc doctrine:migration:migrate

# mtc doctrine:schema:update --force

# mtc cache:clear

Start the update process to latest 2.+ version

# mtc mautic:update:find

Version 2.16.5 of Mautic is available for download. Please visit https://www.mautic.org/blog/community/security-release-all-versions-mautic-prior-2-16-5-and-3-2-3 for more information.
To update, you can run 'php app/console mautic:update:apply' from the command line.

# mtc mautic:update:apply

To avoid permission issues, we run a script that simplifies this procedure.

vi /usr/local/sbin/mtc_permissions.sh

And add the code.

#!/bin/sh

cd /var/www/mautic
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R g+w app/cache/
chmod -R g+w app/logs/
chmod -R g+w app/config/
chmod -R g+w media/files/
chmod -R g+w media/images/
chmod -R g+w translations/
chown -R www-data:www-data .

Make it executable.

# chmod +x /usr/local/sbin/mtc_permissions.sh

And finally run it.

# /usr/local/sbin/mtc_permissions.sh

Clear cache once more.

# mtc cache:clear

Go to your webbrowser and try to login in to your dashboard.

Check the root directory of your Mautic app for file “upgrade_v3.php”.

# ls -al /var/www/mautic/

total 83
drwxr-xr-x  8 www-data www-data    17 Sep  5 15:23 .
drwxr-xr-x  4 root     root         4 Dec 18  2019 ..
-rw-r--r--  1 www-data www-data  5586 Sep  5 15:23 .htaccess
-rw-r--r--  1 www-data www-data 38407 Sep  5 15:23 LICENSE.txt
-rw-r--r--  1 www-data www-data   101 Sep  5 15:23 SECURITY.md
drwxr-xr-x  9 www-data www-data    17 Oct  8  2019 app
-rw-r--r--  1 www-data www-data    18 Sep  5 15:23 critical_migrations.txt
-rw-r--r--  1 www-data www-data 12862 Sep  5 15:23 favicon.ico
-rw-r--r--  1 www-data www-data  1049 Sep  5 15:23 index.php
drwxr-xr-x  7 www-data www-data     7 Oct  8  2019 media
-rw-r--r--  1 www-data www-data  4043 Sep  5 15:23 offline.php
drwxr-xr-x 13 www-data www-data    14 Oct  8  2019 plugins
-rw-r--r--  1 www-data www-data   224 Sep  5 15:23 robots.txt
drwxr-xr-x 19 www-data www-data    21 Oct  8  2019 themes
drwxrwxr-x  2 www-data www-data     3 Oct  8  2019 translations
-rw-r--r--  1 www-data www-data 91666 Sep  5 15:23 upgrade_v3.php
drwxr-xr-x 56 www-data www-data    58 Sep  5 15:23 vendor

Upgrade to php7.3

# apt install software-properties-common -y

# add-apt-repository ppa:ondrej/php

# apt update -y

# apt install php7.3 -y

# apt install php7.3-common php7.3-mysql php7.3-xml php7.3-xmlrpc php7.3-curl php7.3-gd php7.3-imagick php7.3-cli php7.3-dev php7.3-imap php7.3-mbstring php7.3-opcache php7.3-soap php7.3-zip php7.3-intl -y

Modify the php.ini file for php7.3 to meet the requirements of Mautic.

# vi /etc/php/7.3/apache2/php.ini

short_open_tag = On
memory_limit = 256M
upload_max_filesize = 128M
max_execution_time = 360
post_max_size = 128M

# a2enmod php7.3

# a2dismod php7.2

# systemctl restart apache2

# php -v

Upgrade MariaDB database

# mysqldump --all-databases > all-db-$(date +"%m-%d-%y").sql

Remove existing MariaDB server.

# apt remove mariadb-server

# apt-key adv --recv-keys --keyserver hkp://keyserver.ubuntu.com:80 0xF1656F24C74CD1D8

# vi /etc/apt/sources.list.d/mariadb.list

And add.

deb [arch=amd64,arm64,ppc64el] http://nyc2.mirrors.digitalocean.com/mariadb/repo/10.4/ubuntu bionic main
deb-src http://nyc2.mirrors.digitalocean.com/mariadb/repo/10.4/ubuntu bionic main

# apt update

# apt install mariadb-server -y

Go to your webbrowser and try login in to your dashboard.

Now it is time to upgrade to v3.

# sudo -Hu www-data php /var/www/mautic/upgrade_v3.php

In Mautic v3 the console is located in a new directory “bin” so we need to make a few adjustments.

For our “mtc” alias.

# sed -i "s/\/var\/www\/mautic\/app\/console/\/var\/www\/mautic\/bin\/console/g" .bashrc

# exec bash

And for the cronjobs

# sed -i "s/\/var\/www\/mautic\/app\/console/\/var\/www\/mautic\/bin\/console/g" /etc/crontab

Time to upgrade to the latest v3 version.

# mtc mautic:update:find

# mtc mautic:update:apply

# mtc mautic:update:apply --finish

In Mautic v3 both the “cache” and “logs” directory have been moved from the “app” directory to the new “var” directory. Before running our permission script we need to adjust these settings.

# sed -i "s/app\/cache\//var\/cache\//g;s/app\/logs\//var\/logs\//g" /usr/local/sbin/mtc_permissions.sh

Now run the script.

# /usr/local/sbin/mtc_permissions.sh

Clear the cache.

# mtc cache:clear

You should now be running the latest version.

If you are running Mautic on a VPS or LXC/LXD container you might want to take another snapshot.