Operating System CentOS

How to Install Mautic 7 on Ubuntu 24.04 LTS with Apache and MariaDB

Mautic 7 needs PHP 8.2+ with the imap extension and MariaDB 10.11+. Ubuntu 24.04 meets that with stock packages; here is the complete setup.

Mautic is an open source marketing automation platform written in PHP: contacts, segments, email campaigns, forms and landing pages in one self-hosted application. This guide installs Mautic 7, the current major version, on Ubuntu 24.04 LTS with Apache, PHP 8.3 and MariaDB, secures it with a Let's Encrypt certificate and sets up the cron jobs Mautic cannot work without.

CentOS 7 reached end of life in June 2024. Its direct successors, AlmaLinux 9 and Rocky Linux 9, are not a convenient base for Mautic 7, and neither are the very newest Debian and Ubuntu releases, for one specific reason explained below. Ubuntu 24.04 LTS is the supported distribution on which every Mautic 7 requirement is met by stock packages.

Requirements and choice of platform

Mautic 7 requires:

  • PHP 8.2, 8.3, 8.4 or 8.5
  • MySQL 8.4 or later, or MariaDB 10.11 or later, with InnoDB
  • The PHP extensions ctype, curl, dom, fileinfo, iconv, imap, intl, json, mbstring, openssl, pdo_mysql, posix, session, simplexml, tokenizer, xml, zip and zlib
  • Apache with mod_rewrite, or nginx with equivalent rewrite rules

The imap extension decides the platform. It was removed from the PHP core in PHP 8.4, and distributions that ship PHP 8.4 or newer (Debian 13, Ubuntu 26.04) no longer package it. AlmaLinux 9 and Rocky Linux 9 offer PHP 8.3 as a module stream but have no php-imap package in AppStream either. Ubuntu 24.04 ships PHP 8.3 including php-imap and MariaDB 10.11, so nothing has to come from a third-party repository. On the other systems you would need an additional PHP repository or the Mautic container image.

You also need:

  • An Ubuntu 24.04 server with a sudo user (the examples use deploy). Mautic recommends a VPS or dedicated server rather than shared hosting.
  • A DNS record such as mautic.example.com pointing to the server, and ports 80 and 443 open.
  • SMTP credentials or an email delivery service for outgoing mail.

Step 1: Install Apache, PHP and MariaDB

sudo apt update
sudo apt install -y apache2 libapache2-mod-php php-cli php-mysql php-curl php-mbstring \
  php-xml php-zip php-intl php-imap mariadb-server unzip certbot python3-certbot-apache

Mautic asks for a PHP max_execution_time of at least 240 seconds. Set it for Apache only, so that long-running command-line jobs keep their unlimited default:

echo "max_execution_time = 240" | sudo tee /etc/php/8.3/mods-available/mautic.ini
sudo phpenmod -s apache2 mautic

Step 2: Create the database

sudo mariadb
CREATE DATABASE mautic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mautic'@'localhost' IDENTIFIED BY 'CHANGE_ME';
GRANT ALL PRIVILEGES ON mautic.* TO 'mautic'@'localhost';
EXIT;

Step 3: Download Mautic

Production packages are attached to each release on the Mautic GitHub releases page and linked from mautic.org/download. Check there for the newest 7.x version; these commands use 7.2.2.

cd /tmp
curl -LO https://github.com/mautic/mautic/releases/download/7.2.2/7.2.2.zip
sudo mkdir /var/www/mautic
sudo unzip -q 7.2.2.zip -d /var/www/mautic
sudo chown -R www-data:www-data /var/www/mautic

The web server user must own the files: Mautic writes its configuration, cache, logs, uploaded media and its own updates into this directory.

Step 4: Configure Apache

The production package is served from its top-level directory and brings an .htaccess file with the rewrite rules, so Apache must allow overrides there. Create /etc/apache2/sites-available/mautic.conf:

<VirtualHost *:80>
    ServerName mautic.example.com
    DocumentRoot /var/www/mautic

    <Directory /var/www/mautic>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/mautic-error.log
    CustomLog ${APACHE_LOG_DIR}/mautic-access.log combined
</VirtualHost>

Enable the rewrite module and the site, disable the default site and restart Apache:

sudo a2enmod rewrite
sudo a2ensite mautic
sudo a2dissite 000-default
sudo apache2ctl configtest
sudo systemctl restart apache2

Request a certificate; Certbot creates the HTTPS virtual host and the redirect for you:

sudo certbot --apache -d mautic.example.com

Step 5: Run the installer

You can finish the installation in the browser or on the command line.

Web installer

Open https://mautic.example.com. The installer first checks the environment: errors shown in red must be fixed before you can continue, while orange warnings are recommendations. Then enter the database details from step 2 (host localhost, port 3306; switch off the option to back up existing tables on a new installation), create the administrator account and enter your email settings.

Command-line installer

The same can be done in one command, run as the web server user. The administrator password has to be a strong one, otherwise the installer rejects it.

cd /var/www/mautic
sudo -u www-data php bin/console mautic:install https://mautic.example.com \
  --db_driver="pdo_mysql" --db_host="localhost" --db_port="3306" \
  --db_name="mautic" --db_user="mautic" --db_password="CHANGE_ME" \
  --db_backup_tables="false" \
  --admin_firstname="Site" --admin_lastname="Admin" --admin_username="admin" \
  --admin_email="admin@example.com" --admin_password="CHANGE_ME_TOO" \
  --mailer_from_name="Example" --mailer_from_email="marketing@example.com"

All available options are listed by php bin/console mautic:install --help.

Step 6: Add the cron jobs

Segments, campaigns and scheduled emails are only processed when Mautic's console commands run. Without cron jobs, contacts never enter segments and campaigns never fire. Edit the crontab of the web server user:

sudo crontab -u www-data -e

Add the three required jobs. The Mautic documentation strongly recommends staggering them so that they do not start in the same minute:

0,15,30,45 * * * * php /var/www/mautic/bin/console mautic:segments:update --no-interaction --no-ansi
5,20,35,50 * * * * php /var/www/mautic/bin/console mautic:campaigns:update --no-interaction --no-ansi
10,25,40,55 * * * * php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction --no-ansi

Depending on the features you use, add the optional jobs as well:

# Send queued email (when the email queue is enabled)
*/5 * * * * php /var/www/mautic/bin/console messenger:consume email --time-limit=160 --no-interaction --no-ansi
# Send scheduled segment emails (broadcasts)
*/10 * * * * php /var/www/mautic/bin/console mautic:broadcasts:send --no-interaction --no-ansi
# Process contact imports started in the interface
*/10 * * * * php /var/www/mautic/bin/console mautic:import --no-interaction --no-ansi
# Deliver queued webhooks
*/5 * * * * php /var/www/mautic/bin/console mautic:webhooks:process --no-interaction --no-ansi

The intervals of the optional jobs are examples; choose them to fit your sending volume. To debug a job, append >> /var/www/mautic/var/logs/cron.log 2>&1 to its line and read the file.

Verify the installation

Sign in at https://mautic.example.com with the administrator account. Then run one of the cron commands by hand as the web server user; it should finish without errors:

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

Send yourself a test email from the email settings in Settings > Configuration to confirm that the mail transport works. Application errors are logged in /var/www/mautic/var/logs/.

Updating Mautic

Take a tested backup of the files and the database before every update. Then update on the command line, which is more reliable than the in-browser updater for large instances:

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

Read the release notes first; the full procedure is in the Mautic update documentation.

Frequently asked questions

Can I use MySQL instead of MariaDB?

Yes, but Mautic 7 needs MySQL 8.4 or later. Ubuntu 24.04 ships MySQL 8.0, which is too old, so you would have to install MySQL 8.4 from Oracle's own APT repository. The packaged MariaDB 10.11 meets the requirement as it is.

Should I install with Composer instead of the zip package?

Composer (composer create-project mautic/recommended-project) is the better choice if you manage plugins and themes as Composer dependencies or deploy from version control. Note that a Composer-based project keeps the application in a docroot subdirectory, and the web server must then point there instead of the project root. For a single server that you update through Mautic's own updater, the production package is simpler.

Emails stay in the queue and are never sent. Why?

When Mautic is configured to queue email instead of sending immediately, messages wait until messenger:consume email runs. Make sure that cron job exists, and run the command once by hand as www-data to see any transport error directly.

Why do the cron jobs run as www-data?

The console commands write to the same cache and log directories as the web application. If they ran as root, they would leave root-owned files behind and the web interface would fail with permission errors on the next request.

Share story:

Continue reading other guides on How VPS.