How to install Mautic 7 with Composer, Apache, MariaDB and HTTPS

Mautic is an open-source marketing automation platform: it tracks contacts, builds segments, runs multi-step campaigns and sends emails, with forms and landing pages to capture leads. This guide installs Mautic 7 from the official Composer project, which Mautic's documentation names as the default way to install, update and manage Mautic since Mautic 6. Apache with PHP and MariaDB runs Mautic on a local port, Caddy in front provides automatic HTTPS, the installer runs from the shell, cron runs the background jobs, and a transactional email service delivers your messages. Backups, updates and troubleshooting complete the setup.

Step 1 — Install Apache, PHP, MariaDB and Composer

Install the web server, PHP with every extension on Mautic's list, the database server and Composer from your distribution:

sudo apt update
sudo apt install apache2 libapache2-mod-php php-cli php-mysql php-xml php-imap php-zip php-intl php-curl php-gd php-mbstring php-bcmath mariadb-server composer unzip git
php -v
php -m | grep -E 'imap|intl|bcmath|zip|gd|mbstring|curl|xml|mysql'
composer --version

php -v prints 8.3 on Ubuntu 24.04 and 8.2 on Debian 12, and the grep lists each required extension.

Step 2 — Install Node.js for the asset build

Since Mautic 5, npm is required: the Composer project runs npm ci and builds Mautic's front-end assets during installation and every update. Mautic's official Docker image uses Node.js 24 from NodeSource, so install the same from NodeSource's apt repository:

sudo apt install ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

NODE_MAJOR=24
sudo tee /etc/apt/sources.list.d/nodesource.sources <<EOF
Types: deb
URIs: https://deb.nodesource.com/node_${NODE_MAJOR}.x/
Suites: nodistro
Components: main
Signed-By: /etc/apt/keyrings/nodesource.gpg
EOF
sudo apt update
sudo apt install nodejs
node -v
npm -v

node -v should print a v24 version.

Step 3 — Tune PHP and create the database

Raise the PHP limits for the web server to the values Mautic's official image uses. The file path contains your PHP version, so read it into a variable first:

PHPV=$(php -r 'echo PHP_MAJOR_VERSION.".".PHP_MINOR_VERSION;')
echo $PHPV
sudo nano /etc/php/$PHPV/apache2/conf.d/99-mautic.ini

memory_limit = 512M
max_execution_time = 300
upload_max_filesize = 512M
post_max_size = 512M
date.timezone = UTC

max_execution_time = 300 satisfies Mautic's minimum of 240 seconds. The command-line PHP used by Composer and cron keeps its own defaults, which have no execution time limit.

Generate a password for the database user with openssl rand -hex 24, then open the MariaDB shell as root (sudo mariadb) and create the database and user. Replace change-me with the generated password:

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';
FLUSH PRIVILEGES;
EXIT;

MariaDB listens only on localhost in the default Ubuntu and Debian configuration, so it needs no firewall rule.

Step 4 — Download Mautic with Composer

Mautic writes its configuration, cache, logs and media at runtime, so the whole project belongs to the web server user www-data, and every Composer and console command runs as that user. Composer and npm also need a writable home directory for their caches; give them /var/lib/mautic-build, which is outside the web root:

sudo mkdir -p /var/www/mautic /var/lib/mautic-build
sudo chown www-data:www-data /var/www/mautic /var/lib/mautic-build
cd /var/www/mautic
sudo -u www-data env HOME=/var/lib/mautic-build composer create-project mautic/recommended-project:^7.0 /var/www/mautic --no-interaction

^7.0 selects the latest Mautic 7 release. The command downloads Mautic and its plugins and themes, runs npm ci and generates the assets, which takes several minutes. When it finishes, check the layout:

ls /var/www/mautic

You should see bin, config, docroot, var and composer.json. Only docroot is served to the web; configuration and logs stay outside it.

Step 5 — Run the installer from the command line

Mautic also has a web installer, but it is reachable by anyone who finds the address before you finish. The command-line installer avoids that window. Run it as www-data with your public address, the database details from Step 3 and a strong admin password (Mautic requires a complex password since version 5.1):

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=Ada --admin_lastname=Admin --admin_username=admin --admin_email[email protected] --admin_password='Change-me-to-a-long-Passw0rd'

The installer checks the requirements, creates the schema, loads the default data and creates the admin user. It stops with an error message if something critical is missing. Afterwards, config/local.php exists and holds the database settings and secret key; it belongs to www-data and is not inside docroot.

Step 6 — Serve Mautic with Apache on a local port

Apache serves PHP with the .htaccess rules shipped in docroot; Caddy will sit in front of it. Move Apache from port 80 to 127.0.0.1:8080 and turn off the default site:

sudo sed -i 's/^Listen 80$/Listen 127.0.0.1:8080/' /etc/apache2/ports.conf
sudo a2dissite 000-default
sudo a2enmod rewrite setenvif
sudo nano /etc/apache2/sites-available/mautic.conf

Paste this virtual host. AllowOverride All activates Mautic's .htaccess rules, and the SetEnvIf line tells PHP that the original request used HTTPS when Caddy says so; only Caddy can reach this port, so the header can be trusted:

<VirtualHost 127.0.0.1:8080>
    ServerName mautic.example.com
    DocumentRoot /var/www/mautic/docroot

    SetEnvIf X-Forwarded-Proto "^https$" HTTPS=on

    <Directory /var/www/mautic/docroot>
        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 site, test the configuration and restart Apache:

sudo a2ensite mautic
sudo apache2ctl configtest
sudo systemctl restart apache2
sudo ss -tlnp | grep apache2
curl -I http://127.0.0.1:8080/

configtest prints Syntax OK, ss shows Apache on 127.0.0.1:8080 only, and curl gets an HTTP answer from Mautic, typically a redirect to the login page.

Step 7 — Add HTTPS with Caddy and set trusted proxies

Add a site block to /etc/caddy/Caddyfile and reload Caddy:

mautic.example.com {
    reverse_proxy 127.0.0.1:8080
}

sudo systemctl reload caddy
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Open https://mautic.example.com and log in with the admin account from Step 5. Then open Settings (the cog icon) → Configuration → System Settings and set:

• Site URL: https://mautic.example.com.
• Trusted proxies: 127.0.0.1. Mautic's documentation calls this setting mandatory behind an SSL-terminating proxy; it also lets Mautic see the real visitor IP from Caddy's X-Forwarded-For header instead of 127.0.0.1, which tracking relies on.
• Trusted hosts: mautic.example.com, so Mautic answers only to your own hostname.

Step 8 — Schedule the cron jobs

Segments, campaigns and segment emails are processed only by cron jobs. Mautic lists the segment update, campaign update, campaign trigger, message queue and custom-field jobs as required, and recommends staggering them so they never start in the same minute. Create /etc/cron.d/mautic with sudo nano /etc/cron.d/mautic; each line runs as www-data:

0,15,30,45 * * * * www-data php /var/www/mautic/bin/console mautic:segments:update --no-interaction --no-ansi
5,20,35,50 * * * * www-data php /var/www/mautic/bin/console mautic:campaigns:update --no-interaction --no-ansi
10,25,40,55 * * * * www-data php /var/www/mautic/bin/console mautic:campaigns:trigger --no-interaction --no-ansi
2,17,32,47 * * * * www-data php /var/www/mautic/bin/console mautic:messages:send --no-interaction --no-ansi
7,22,37,52 * * * * www-data php /var/www/mautic/bin/console mautic:broadcasts:send --no-interaction --no-ansi
12,42 * * * * www-data php /var/www/mautic/bin/console mautic:custom-field:create-column --no-interaction --no-ansi
13,43 * * * * www-data php /var/www/mautic/bin/console mautic:custom-field:delete-column --no-interaction --no-ansi
8,23,38,53 * * * * www-data php /var/www/mautic/bin/console mautic:import --no-interaction --no-ansi
3,33 * * * * www-data php /var/www/mautic/bin/console mautic:reports:scheduler --no-interaction --no-ansi

The first three timings come from Mautic's documentation; the others are spread over free minutes. mautic:broadcasts:send sends segment emails, mautic:import handles large CSV imports in the background, and mautic:reports:scheduler emails scheduled reports. Mautic documents further optional jobs, such as mautic:email:fetch for bounce handling and mautic:webhooks:process for queued webhooks; add them when you use those features. Run one job by hand to see its output, then confirm that cron picks the file up:

sudo -u www-data php /var/www/mautic/bin/console mautic:segments:update --no-interaction
journalctl -u cron --since "30 min ago"

Step 9 — Connect an email service

Mautic sends email through Symfony Mailer with an SMTP DSN in the form smtp://user:[email protected]:587. In Settings → Configuration → Email Settings, set the sender name and an address on a domain you control, then enter the SMTP host, port 587, user name and password from your transactional email provider or SMTP relay; Symfony Mailer upgrades the connection on port 587 with STARTTLS. Publish the SPF, DKIM and DMARC records your provider gives you, or your messages will land in spam.

To test delivery end to end, create a segment that contains only your own contact, send it an email, and check that the message arrives and its links are tracked through https://mautic.example.com.

Back up and restore

Mautic's state is the MariaDB database plus the project folder: config/local.php (database settings and secret key), uploaded media in docroot/media, and your composer.json and composer.lock. Dump the database with --single-transaction, which gives a consistent InnoDB snapshot without blocking Mautic, and archive the project without caches and node_modules:

sudo mkdir -p /opt/backups
sudo chown $USER:$USER /opt/backups
chmod 700 /opt/backups
sudo mariadb-dump --single-transaction --quick mautic | gzip > /opt/backups/mautic-db-$(date +%F).sql.gz
sudo tar czf /opt/backups/mautic-files-$(date +%F).tar.gz -C /var/www --exclude=mautic/node_modules --exclude=mautic/var/cache mautic

Keep copies of /etc/apache2/sites-available/mautic.conf, /etc/cron.d/mautic and the PHP settings file too. To restore, stop Apache, unpack the files, import the dump and clear the cache. Replace the dates with those of your backup:

sudo systemctl stop apache2
sudo tar xzf /opt/backups/mautic-files-2026-10-09.tar.gz -C /var/www
sudo chown -R www-data:www-data /var/www/mautic
gunzip -c /opt/backups/mautic-db-2026-10-09.sql.gz | sudo mariadb mautic
sudo -u www-data php /var/www/mautic/bin/console cache:clear
sudo systemctl start apache2

On a new server, run Steps 1 to 3 and Step 6 first, restore, and then run sudo -u www-data env HOME=/var/lib/mautic-build composer install in /var/www/mautic to rebuild node_modules. Copy every backup off the server and test a restore regularly.

Update Mautic

Mautic's update guide says never to update without a working, tested backup, and to check the release notes for new requirements such as a higher PHP version. The Composer constraint ^7.0 already allows every Mautic 7 release; for a new major version, first change the Mautic package versions in composer.json as the release notes describe. Then save the current Composer files, update, and finish with the database steps from the documentation:

cd /var/www/mautic
sudo -u www-data cp composer.json composer.json.bak
sudo -u www-data cp composer.lock composer.lock.bak
sudo -u www-data env HOME=/var/lib/mautic-build composer update --with-dependencies
sudo -u www-data php bin/console cache:clear
sudo -u www-data php bin/console mautic:update:apply --finish
sudo -u www-data php bin/console doctrine:migration:migrate --no-interaction
sudo -u www-data php bin/console cache:clear

If the update fails, restore the two .bak files and run composer install as above to return to the previous versions, then restore the database from your backup. The recommended project suggests keeping the whole folder in a Git repository, so git diff shows when an update changes scaffolded files such as docroot/.htaccess. Keep PHP, Apache and MariaDB patched with sudo apt update && sudo apt upgrade.

Troubleshooting

Apache fails to start with Address already in use

Another service, usually Caddy, already listens on port 80. Make sure Step 6 changed ports.conf to Listen 127.0.0.1:8080, check with sudo ss -tlnp | grep -E ':80 |:8080 ', then run sudo systemctl restart apache2.

Composer stops because a PHP extension is missing

Mautic's Composer files require ext-imap, ext-zip, ext-iconv, ext-pdo and ext-zlib, plus the extensions on the requirements page. Install the missing php- package from Step 1, confirm with php -m, and run the Composer command again. On releases with PHP 8.4, php-imap is not available; use Ubuntu 24.04 or Debian 12.

Login loops or Mautic builds http:// links

Mautic does not know the request came over HTTPS. Check the SetEnvIf line in the Apache site, set Trusted proxies to 127.0.0.1 and the Site URL to the https:// address in System Settings, then clear the cache.

Segments, campaigns or segment emails never run

The cron jobs are missing or failing. Check that /etc/cron.d/mautic belongs to root, has no dot in its name and ends with a newline, read journalctl -u cron, and run the failing command by hand as www-data to see the error. Application errors are logged in /var/www/mautic/var/logs.

Emails are not delivered

Check the SMTP host, port, user name and password in Email Settings, make sure your provider has verified the sender domain, and read the newest log file in /var/www/mautic/var/logs. Outbound connections to your provider's port 587 must be allowed by any firewall between the server and the provider.

Next steps

• Compare a lighter newsletter tool: How to install listmonk.
• Connect marketing to sales with How to install Odoo.
• See server options for email marketing on the Email marketing hosting page.
• Read Mautic's cron jobs documentation for every optional job and its options.