How To Install Mautic on Debian 12

Mautic stands as the leading open-source marketing automation platform, offering organizations of all sizes an affordable alternative to expensive proprietary solutions. Installing it on Debian 12 provides an ideal foundation due to the operating system’s renowned stability, security, and long-term support. This comprehensive guide walks you through the complete installation process with detailed steps from preparation to post-installation optimization.

Prerequisites and System Requirements

Before beginning the installation, ensure your system meets these requirements for optimal Mautic performance:

Hardware Requirements:

• CPU: Minimum 2 cores (4+ cores recommended for production)
• RAM: 2GB minimum (4GB+ recommended)
• Storage: 20GB+ available space (SSD storage preferred)
• Network: Reliable internet connection with sufficient bandwidth

Server Requirements:

• Dedicated server or VPS running Debian 12 (Bookworm)
• Public IP address with properly configured DNS
• Domain or subdomain pointing to your server
• SSH access with root or sudo privileges

Software Components:

• Web server: Apache 2.4 or Nginx
• Database: MariaDB 10.5+ or MySQL 8.0+
• PHP: Version 8.1 or 8.2 with required extensions
• Additional tools: Composer (PHP dependency manager)

Taking time to properly prepare these prerequisites ensures a smoother installation process and better performance for your marketing automation platform.

Step 1: Preparing the Debian 12 System

Begin by connecting to your Debian 12 server via SSH and preparing the system for Mautic installation.

First, update the system packages to ensure you have the latest security patches:

sudo apt update
sudo apt upgrade -y

Install essential utilities needed for the installation process:

sudo apt install -y apt-transport-https ca-certificates curl software-properties-common gnupg2 unzip wget git

Configure the server timezone, which is crucial for scheduled campaigns and proper logging:

sudo timedatectl set-timezone your_timezone

Replace your_timezone with appropriate values like America/New_York or Europe/London.

Verify the timezone setting:

timedatectl status

Adjust system performance parameters for better operation:

echo 'vm.swappiness=10' | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Step 2: Setting Up Required Repositories

Mautic requires specific versions of PHP and MariaDB that may not be available in Debian’s default repositories.

Add the Sury PHP repository for PHP 8.2 and required extensions:

sudo apt install -y lsb-release apt-transport-https ca-certificates curl
curl -sSLo /usr/share/keyrings/deb.sury.org-php.gpg https://packages.sury.org/php/apt.gpg
echo "deb [signed-by=/usr/share/keyrings/deb.sury.org-php.gpg] https://packages.sury.org/php/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/php.list

Add the official MariaDB repository:

curl -sS https://downloads.mariadb.com/MariaDB/mariadb_repo_setup | sudo bash

Update package lists to include these new repositories:

sudo apt update

If you encounter GPG key errors, manually import them:

sudo apt-key adv --fetch-keys https://packages.sury.org/php/apt.gpg
sudo apt-key adv --fetch-keys https://mariadb.org/mariadb_release_signing_key.pgp

Step 3: Installing Required Packages

Now install all the necessary components for your Mautic system.

Install Apache web server:

sudo apt install -y apache2
sudo a2enmod rewrite ssl headers
sudo systemctl start apache2
sudo systemctl enable apache2

Install PHP 8.2 with all extensions required by Mautic:

sudo apt install -y php8.2 php8.2-cli php8.2-common php8.2-curl php8.2-gd php8.2-intl php8.2-mbstring php8.2-mysql php8.2-opcache php8.2-xml php8.2-zip php8.2-bcmath php8.2-fpm php8.2-imap php8.2-apcu

Install MariaDB server:

sudo apt install -y mariadb-server
sudo systemctl start mariadb
sudo systemctl enable mariadb

Install additional utilities for your Mautic installation:

sudo apt install -y zip unzip acl imagemagick postfix

Install Composer for PHP dependency management:

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"

When prompted during Postfix installation, select “Internet Site” and enter your server’s fully qualified domain name.

Step 4: Configuring PHP for Mautic

Optimizing PHP configuration is critical for Mautic’s performance. Create a backup of the original config:

sudo cp /etc/php/8.2/apache2/php.ini /etc/php/8.2/apache2/php.ini.backup

Edit the PHP configuration:

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

Modify these key settings:

memory_limit = 256M
upload_max_filesize = 100M
post_max_size = 100M
max_execution_time = 300
max_input_time = 300
date.timezone = Your/Timezone

Apply the same changes to PHP-FPM:

sudo cp /etc/php/8.2/fpm/php.ini /etc/php/8.2/fpm/php.ini.backup
sudo nano /etc/php/8.2/fpm/php.ini

Configure PHP-FPM for optimal performance:

sudo nano /etc/php/8.2/fpm/pool.d/www.conf

Modify these settings according to your server resources:

pm = dynamic
pm.max_children = 50
pm.start_servers = 5
pm.min_spare_servers = 5
pm.max_spare_servers = 35

Restart PHP-FPM to apply changes:

sudo systemctl restart php8.2-fpm

Step 5: Configuring MariaDB Database

Secure your MariaDB installation and create a database for Mautic:

sudo mysql_secure_installation

Follow the prompts to set a root password and secure your installation.

Log in to MariaDB and create the database and user for Mautic:

sudo mysql -u root -p

Run these SQL commands:

CREATE DATABASE mautic CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'mauticuser'@'localhost' IDENTIFIED BY 'strong_password';
GRANT ALL PRIVILEGES ON mautic.* TO 'mauticuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Replace ‘strong_password’ with a secure password of your choice.

Optimize MariaDB for better performance:

sudo nano /etc/mysql/mariadb.conf.d/50-server.cnf

Add these settings under the [mysqld] section:

innodb_buffer_pool_size = 256M
innodb_log_file_size = 64M
max_allowed_packet = 64M
join_buffer_size = 2M

Restart MariaDB to apply changes:

sudo systemctl restart mariadb

Step 6: Configuring Web Server

Create a directory for Mautic:

sudo mkdir -p /var/www/mautic
sudo chown www-data:www-data /var/www/mautic
sudo chmod 755 /var/www/mautic

Create an Apache virtual host configuration:

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

Add this configuration:

<VirtualHost *:80>
    ServerAdmin webmaster@yourdomain.com
    ServerName mautic.yourdomain.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>

Configure PHP-FPM with Apache:

sudo a2enconf php8.2-fpm

Enable the virtual host and restart Apache:

sudo a2ensite mautic.conf
sudo systemctl restart apache2

For enhanced security, set up SSL with Let’s Encrypt:

sudo apt install -y certbot python3-certbot-apache
sudo certbot --apache -d mautic.yourdomain.com

Step 7: Installing Mautic

Download the latest Mautic release:

cd /tmp
wget https://github.com/mautic/mautic/releases/download/4.4.8/4.4.8.zip

Extract it to your web directory:

sudo unzip 4.4.8.zip -d /var/www/mautic

Set proper permissions:

sudo chown -R www-data:www-data /var/www/mautic
sudo find /var/www/mautic -type d -exec chmod 755 {} \;
sudo find /var/www/mautic -type f -exec chmod 644 {} \;

Create and set permissions for directories that need write access:

sudo mkdir -p /var/www/mautic/var/{cache,logs,sessions}
sudo chmod -R 775 /var/www/mautic/var/{cache,logs,sessions}
sudo chmod -R 775 /var/www/mautic/app/config
sudo chmod -R 775 /var/www/mautic/media
sudo chmod -R 775 /var/www/mautic/translations

Create the local configuration file:

sudo touch /var/www/mautic/app/config/local.php
sudo chown www-data:www-data /var/www/mautic/app/config/local.php
sudo chmod 664 /var/www/mautic/app/config/local.php

Step 8: Running the Mautic Web Installer

Open your web browser and navigate to your Mautic domain:
http://mautic.yourdomain.com

Follow the web installer steps:

1. Select your preferred language
2. Review system requirements
3. Configure database connection:
   • Database Driver: MySQL (PDO)
   • Database Host: localhost
   • Database Name: mautic
   • Database Username: mauticuser
   • Database Password: your_password
4. Create administrator account:
   • Username, password, email, name
5. Configure email settings:
   • Email Transport: SMTP recommended
   • SMTP Host, Port, Security, Username, Password

Click “Install” to complete the process. The installer will create database tables and prepare the system for first use.

Step 9: Post-Installation Tasks

Set up required cron jobs for Mautic’s scheduled tasks:

sudo crontab -u www-data -e

Add these entries:

# Mautic cron jobs
*/5 * * * * php /var/www/mautic/bin/console mautic:campaigns:trigger
*/10 * * * * php /var/www/mautic/bin/console mautic:emails:send
*/15 * * * * php /var/www/mautic/bin/console mautic:import
0 * * * * php /var/www/mautic/bin/console mautic:segments:update
0 0 * * * php /var/www/mautic/bin/console mautic:maintenance:cleanup

Clear Mautic’s cache:

sudo -u www-data php /var/www/mautic/bin/console cache:clear

Implement basic security measures:

sudo apt install -y ufw fail2ban
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

Troubleshooting Common Issues

Permission Problems:
If you encounter file permission errors:

sudo chown -R www-data:www-data /var/www/mautic
sudo find /var/www/mautic -type d -exec chmod 755 {} \;
sudo find /var/www/mautic -type f -exec chmod 644 {} \;
sudo chmod -R 775 /var/www/mautic/var/{cache,logs,sessions}

Database Connection Issues:
Verify database credentials:

mysql -u mauticuser -p -D mautic

Reset database permissions if needed:

sudo mysql -u root -p -e "GRANT ALL PRIVILEGES ON mautic.* TO 'mauticuser'@'localhost'; FLUSH PRIVILEGES;"

PHP Configuration Problems:
Check and adjust PHP settings:

php -i | grep memory_limit
sudo nano /etc/php/8.2/apache2/php.ini

Web Server Errors:
Check Apache logs:

sudo tail -f /var/log/apache2/error.log

Cron Job Issues:
Test running commands manually:

sudo -u www-data php /var/www/mautic/bin/console mautic:emails:send

Remember to periodically update Mautic to the latest version and back up your database for optimal security and performance.

Congratulations! You have successfully installed Mautic. Thanks for using this tutorial for installing Mautic digital marketing tool on Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the official Mautic website.