After long waiting, it’s time to enjoy Mautic 5. Here is my spin on a composer install with step by step instructions including the new Amazon SES config and new cronjobs.

This tutorial is about a Mautic 5.0.1 fresh installation, and I want you to learn how to maintain your project with composer. Why? Because once you understand how it’s done, and what the advantages are, you’ll love it. The Mautic project did a great job in explaining everything in the docs, and you should read it, but if you want to go with my more narrated way, then knock yourself out:

Part One: The environment

This tutorial is about an Ubuntu 22.05, my preferred way of hosting Mautic. In Part one we set up everything that Mautic needs, and likes. This is important, just like the perfect mediterranean soil for producing good juicy tomatoes.

Before anything else, make sure you point your subdomain to your server. Create an A record, that points at your server.

A subdomain 111.111.111.111

Let’s log in to our ubuntu with our ssh key / password, whatever you like.

Set system timezone

This is an important step, what one might skip. If you want to be sure your Mautic campaigns are running at the right timezone, this setting makes everything easier.

dpkg-reconfigure tzdata

Install prerequisites

Here we are going to make sure we have php 8.1 ready to rock

apt update && apt upgrade -y
apt install software-properties-common
add-apt-repository ppa:ondrej/php
add-apt-repository ppa:ondrej/apache2
apt update && apt upgrade -y

Install required packages

In the step above we just installed a very plain php, so here we go and add some extensions. These extensions make sure, that you can zip, use imap for reading emails, and other important functions. And oh yes, we also install apache webserver and mariadb for running our mysql database.

apt install apache2 mariadb-server libapache2-mod-php8.1 php8.1 php8.1-{xml,mysql,imap,zip,intl,curl,gd,mbstring,bcmath} -y

Configure Apache2

Now we will tell our webserver where to find Mautic, if someone reaches us with the right domain. We will configure Apache2 site configuration file for Mautic. Run the commands below to create a new configuration file called mautic.conf

sudo nano /etc/apache2/sites-available/mautic.conf

Then copy and paste the content below into the file and save it. Replace the highlighted line with your own domain name and directory root location.

Let’s stop for a moment here and look at the config. If you are a Mautic 4 veteran, you might notice, that we need to go 1 folder deeper in mautic, right into the docroot folder. This is not a typo, mautic main files have moved there in Mautic 5. Don’t worry, it’s all for your benefit.

<VirtualHost *:80>
     ServerAdmin admin@yoursite.com
     DocumentRoot /var/www/html/mautic/docroot
     ServerName yoursite.com
     ServerAlias www.yoursite.com

     <Directory /var/www/html/mautic/docroot>
        Options +FollowSymlinks
        AllowOverride All
        Require all granted
     </Directory>

     ErrorLog ${APACHE_LOG_DIR}/error.log
     CustomLog ${APACHE_LOG_DIR}/access.log combined

</VirtualHost>

Create symlink, so your available config will be actually enabled.

sudo ln -s /etc/apache2/sites-available/mautic.conf /etc/apache2/sites-enabled/

Add SSL

sudo add-apt-repository ppa:certbot/certbot
apt update && apt upgrade -y
sudo apt-get install python-certbot-apache

Initiate Certbot setup

certbot --apache -d subdomain.yourdomain.com

Once you configured the VirtualHost as above, you’ll need to enable it by running following the commands:

a2enmod php8.1
a2enmod rewrite

Nice. We have apache installed, configured, and we are running under php 8.1. We are almost done, but as we (I’m looking at you, Mautic) are kinda high maintanance, we need to tweak the settings to accomodate our beloved software’s needs.

Tweak PHP settings

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

Some of these settings will be already set as below, but you still need to make all the necessary changes. The following sed command is for lazy people (they are the smartest), since you don’t need to edit the files line by line, but it overwrites the old value with the desired one. So just copy + paste my friend.

sed -i 's/allow_url_fopen = Off/allow_url_fopen = On/' /etc/php/8.1/apache2/php.ini
sed -i 's/memory_limit = 128M/memory_limit = 512M/' /etc/php/8.1/apache2/php.ini
sed -i 's/upload_max_filesize = 2M/upload_max_filesize = 200M/' /etc/php/8.1/apache2/php.ini
sed -i 's/max_execution_time = 30/max_execution_time = 300/' /etc/php/8.1/apache2/php.ini
sed -i 's/post_max_size = 8M/post_max_size = 64M/' /etc/php/8.1/apache2/php.inifile_uploads = On

You should also set your timezone. Open the file with

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

Use CTRL+W for search and enter date.timezone. Now add your timezone, based on the following list:

List of Supported Timezones

Example:

date.timezone = Europe/Budapest

When you finished, you can close the file with CTRL+X and Y + Enter

Sweet! It is time to restart Apache to validate all changes.

sudo systemctl restart apache2.service

💡 It seems to me, you are eager to learn. You can use the following commands to start / stop / enable apache2:

sudo systemctl stop apache2.service
sudo systemctl start apache2.service
sudo systemctl enable apache2.service

Create our database

As you remember a couple of lines above we already installed mariadb. Now let’s secure our installation.

sudo mysql_secure_installation

When prompted, answer the questions below as follows:

Enter current password for root (enter for none): Just press the Enter
Set root password? [Y/n]: Y
New password: Enter password
Re-enter new password: Repeat password
Remove anonymous users? [Y/n]: Y
Disallow root login remotely? [Y/n]: Y
Remove test database and access to it? [Y/n]: Y
Reload privilege tables now? [Y/n]: Y

Learning time: this is how you stop and restart the database server:

sudo systemctl stop mariadb.service
sudo systemctl start mariadb.service

We still don’t have an empty database yet, just the engine, which will be able to run it, so we will make an empty database first.

We need to log in into our MariaDB database server, with the following commands below.

sudo mysql

Then create a database called mauticdb

CREATE DATABASE mauticdb;

Create a database user called mauticuser with new password. This is a password, which will be used for especially this database. Do not use your root password. (Replace YOURPASS with your secure password) (No, doesn’t have to be capital, it’s just an example, duh!)

CREATE USER 'mauticuser'@'localhost' IDENTIFIED BY 'YOURPASS';

Then grant the user full access to the database. (Make sure you use the password you just gave above)

GRANT ALL ON mauticdb.* TO 'mauticuser'@'localhost' IDENTIFIED BY 'YOURPASS' WITH GRANT OPTION;

We are done, save your changes and exit.

FLUSH PRIVILEGES;
EXIT;

Part Two: The Package managers

Well this part is kinda short, but I think we really need to keep package managers separate. I’ll extend it with time, as we need to talk more and more about how to maintain your project with package managers.

You might think this is useless, but you’ll enjoy using package managers, you you first time used a remote control to switch the channels on your TV instead of getting up and switching the channels manually. (What you never did that? Don’t make me feel old.)

Install NPM

What the what? Is this new?
Yep, npm is a new thing in Mautic, but it’s for your benefit. It will manage all the packages you need when it comes to Javascript. You might ask: “Then why do I need composer?”. Okay, I won’t go into details, let’s just say, two package managers are always better as one…

curl -fsSL <https://deb.nodesource.com/setup_20.x> | sudo -E bash -
sudo apt install -y nodejs
apt install npm

Install Composer

Let’s download the newest version from Github

sudo apt install composer

Yes, that’s it. I told you it’s easy.

Part Three: Install Mautic

Let’s go to our folder where all the mautic files going and create our project. We will go with 5.0.1, this is the latest stable version at the creation of this article.

cd /var/www/html
composer create-project mautic/recommended-project:5.0.0-rc1 mautic --no-interaction
cd mautic/docroot

Add the SSL hack

Since we didn’t run our composer as www-data (I need a tutorial on that), we will need to set ownership and permisssions:

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

Reload apache, to have a nice and clean feeling here

service apache2 reload

If by now you feel like a child on xmas day, you are right. Dry your sweaty palms and open your browser, type in your domain name. You should see Mautic setup wizard.

If everything went fine, you won’t see any environmental recommendations. The rule of thumb is, if you don’t see anything red, we are good to go. Click on Next step.

Fill out the fields with the user names and passwords we used previously. (Remember, YOURPASS)

At the last step we need to create the credentials of our main admin user.

Once you’ve done it, you are good to go.

Warning: from Mautic 5.1 you’ll need to create a strong password. I know you are itching to enter 123456, but let’s consider security a little bit more.

Part Four: Add your email transport

Adding email used to be fairly simple in Mautic previous versions. Now it’s just an extra step, you have to get used to. Since you installed your Mautic with composer, you can call yourself a Composer Ninja, and as such, you’ll enjoy how easy you can add packages to your Mautic installation.

Let’s go to our /var/www/html/mautic folder. No, not to the docroot, as we need to add the package to the vendor folder, where all extra stuff lives, what we need for our Mautic to function.

cd /var/www/html/mautic

This is the place where you have to be before installing anything new in your Mautic. Well, besides plugins, but we talk about that later. Now execute the command to add your email transport. My example will install Amazon SES:

composer require symfony/amazon-mailer
sudo chown -R www-data:www-data /var/www/html/mautic/
sudo chmod -R 755 /var/www/html/mautic/

If you need another transport, you can see the list here: https://symfony.com/doc/5.x/mailer.html

I want you to acknwoledge, this is pretty cool. Now Mautic can benefit from using the mailers created by other projects with no substential effort. Oh, I just love open source.

Now at this part the Mautic documentation can’t be specific enough as it’s more like an overall doc for Mautic. But I’d like to be more specific about Amazon SES.

So here is an example setup, which will work:

Bounce management

I’m sure you are used to the good old Mautic Amazon SES bounce management, where you just add the endpoint to SNS and Mautic processes all the unsubscribe. Well, that is not available in Mautic 5 at the time when this article is written. According to the docs, you should be able to use

https://mautic.example.com/mailer/callback

But it is not working unfortunately. The reason is, that the freshly installed amazon ses transport does not include the feedback loop. In other words: it sends out emails, but doesn’t care about the feedback loop.

I’m sure the community will get it done at one point. Until then you’ll have to use good old bounce inbox management by fetching inboxes.

Part Five: add cronjobs

Okay, so here I have some news as well. Let’s look at the cronjobs, that work just like in Mautic 3/4.

Segments are still rebuilt by:

mautic:segments:rebuild

Campaign related cronjobs are also unchanged:

mautic:campaigns:update
mautic:campaigns:trigger

However here is a new feature, you can use threads to run multiple campaign updates and triggers at the same time! The format looks like this:

  --thread-id[=THREAD-ID]
The number of this current process if running multiple in parallel.
  --max-threads[=MAX-THREADS]
The maximum number of processes you intend to run in parallel.

Imports also unchanged:

mautic:import

Email sending can be now queue or immediate. In order to send via Queue, you’ll need another setup, namely the Redis Queue, which manages your messages going out in a nice organized manner.

The this point I recommend to use immediate send (which is the default, you won’t need to do anything). This is done by the broadcast send command:

mautic:broadcast:send

Here is a nice summary of your cronjobs settings for the user www-data. Open cronjobs with the following command:

sudo crontab -u www-data -e

If you are asked which editor to use, choose nano. Paste the following settings at the bottom:

* * * * * php /var/www/html/mautic/bin/console mautic:broadcasts:send --limit=500
* * * * * php /var/www/html/mautic/bin/console mautic:campaigns:rebuild --batch-limit=100
* * * * * php /var/www/html/mautic/bin/console mautic:segment:update --batch-limit=900
* * * * * php /var/www/html/mautic/bin/console mautic:campaigns:trigger
* * * * * php /var/www/html/mautic/bin/console mautic:import --limit=500
* * * * * php /var/www/html/mautic/bin/console mautic:webhooks:process
* * * * * php /var/www/html/mautic/bin/console mautic:reports:scheduler

This can be used as a basic setting on a decent server with not too many contacts (max 1-5k). But if you want to optimise your cronjobs, check my other blogposts for that.

Now you have a pretty decent Mautic 5 setup. Congrats 🙂

If you have questions, shoot: