This is a small guide to configure doctrine to send the queue. Will be in the kb soon
But since this was a great pain for me for 2 or 3 weeks I want to share it now for any that finds the same issues I did.
I am using CPanel and no docker or any other thing but a simple Linux hosting.
Another thing, this is for Mautic 5, not previous versions.
Detailed Guide: Configuring Mautic for Email Queue Management with Doctrine and Cron Jobs
1. Introduction to the Concept
What is Mautic?
Mautic is an open-source marketing automation platform that enables you to engage with your audience through various channels such as email, SMS, social media, and more. It’s a powerful tool for managing marketing campaigns, segmenting your audience, and tracking engagement.
What is Doctrine?
Doctrine is an Object-Relational Mapper (ORM) for PHP, which is used by Mautic to manage database operations. In the context of this guide, Doctrine also serves as a transport layer for the Symfony Messenger component that Mautic uses to queue and process tasks, such as sending emails.
Why Use a Queue System for Emails?
Sending large volumes of emails directly can overwhelm your server, leading to performance issues or being flagged as spam by recipient email servers. A queue system allows you to process and send emails in smaller, controlled batches, which is more efficient and reduces the likelihood of your emails being marked as spam.
The Importance of Sending Emails in Small Batches
By sending emails in smaller batches, such as 60 emails every 10 minutes, you:
- Reduce server load: Prevent the server from being overwhelmed by processing too many tasks at once.
- Improve deliverability: Lower the chance of being marked as spam due to sending large volumes in a short time.
- Increase reliability: Ensure that your email campaigns are delivered consistently and within acceptable time frames.
Introduction to Lock Files and Their Purpose
A lock file is used to ensure that only one instance of a process runs at a time. This is crucial when dealing with cron jobs that may overlap. By using a lock file, you can prevent multiple instances of the email sending process from running simultaneously, which could cause conflicts or excessive resource consumption.
2. Setting Up Mautic with Doctrine for Email Queues
Option 1: Configuring via local.php File
-
Step 1: Locate the
local.phpFile
Thelocal.phpfile is typically located in theapp/configdirectory of your Mautic installation. This file contains the configuration settings for your Mautic instance. -
Step 2: Edit the Configuration File
To configure Mautic to use Doctrine as the queue transport, you need to edit thelocal.phpfile. Add or modify the following settings:<?php return array( // Other Mautic configuration settings... 'messenger' => [ 'default_bus' => 'messenger.bus.default', 'transports' => [ 'doctrine' => [ 'dsn' => 'doctrine://default?table_name=messenger_messages', ], ], ], // Additional configuration settings... ); -
Step 3: Save the File
After making these changes, save thelocal.phpfile. These settings will now be applied the next time Mautic processes a queue.
Option 2: Configuring via Mautic’s Queue Configuration Screen
-
Step 1: Access the Queue Configuration Screen
- Log in to your Mautic dashboard.
- Navigate to Settings by clicking on the gear icon in the top-right corner.
- Select Queue Settings from the menu.
-
Step 2: Configure the Queue Settings
- Select Doctrine as the Queue Transport:
- In the Queue Transport, type Doctrine. This tells Mautic to use Doctrine for queue management.
- Configure the following settings:
- Scheme: doctrine
- Host: default
- Table Name: messenger_messages (or any custom table name you prefer)
- Save the Configuration:
- Once you’ve entered the correct settings, click the Save & Close button to apply the configuration.
- Select Doctrine as the Queue Transport:
Explanation:
By setting the Queue Transport to Doctrine, you’re instructing Mautic to manage queued emails using Doctrine’s database storage. This allows Mautic to handle email processing more efficiently, especially under heavy loads.
3. Implementing Cron Jobs for Automated Email Sending
Creating the Shell Script
-
Step 1: Create the Script
Place the script in a suitable location, such as/path/to/mautic/var/lock/consume_mautic.sh:#!/bin/bash # Path to the lock file LOCKFILE="/path/to/mautic/var/lock/consume_mautic.lock" # Lock file timeout (9 minutes = 540 seconds) LOCKFILE_TIMEOUT=540 # Check if the lock file exists if [ -e $LOCKFILE ]; then # Calculate the age of the lock file LOCKFILE_AGE=$(($(date +%s) - $(stat -c %Y $LOCKFILE))) # Remove the lock file if it is too old if [ $LOCKFILE_AGE -ge $LOCKFILE_TIMEOUT ]; then echo "Lock file is older than $LOCKFILE_TIMEOUT seconds. Removing..." rm -f $LOCKFILE else echo "Process is already running. Exiting..." exit 1 fi fi # Create the lock file touch $LOCKFILE # Run the messenger:consume command for emails /usr/bin/php /path/to/mautic/bin/console messenger:consume email --limit=60 --time-limit=480 --memory-limit=128M # Remove the lock file when done rm -f $LOCKFILE exit 0 -
Step 2: Make the Script Executable
Give the script execute permissions:chmod +x /path/to/mautic/var/lock/consume_mautic.sh
Configuring the Cron Job
-
Step 1: Open the Crontab
Use the following command to edit your crontab:crontab -e -
Step 2: Add the Cron Job
Add the following line to your crontab:*/10 * * * * /path/to/mautic/var/lock/consume_mautic.sh >> /path/to/mautic/var/logs/mautic_consume.log 2>&1This will run the script every 10 minutes and log the output to
mautic_consume.log.
Setting Up Directories and Permissions
-
Step 1: Create Directories
Ensure that the necessary directories exist and have the correct permissions:mkdir -p /path/to/mautic/var/lock mkdir -p /path/to/mautic/var/logs -
Step 2: Check Permissions
Make sure that the user running the cron job has the necessary permissions to read/write in these directories.
Testing the Setup
-
Step 1: Run the Script Manually
You can run the script manually to ensure it works as expected:/path/to/mautic/var/lock/consume_mautic.sh -
Step 2: Check the Logs
Review the log file to ensure that the emails are being processed:tail -f /path/to/mautic/var/logs/mautic_consume.log
4. Monitoring and Troubleshooting
How to Monitor Logs
Regularly check the log file (mautic_consume.log) to monitor the performance of the email queue and troubleshoot any issues that arise.
Common Issues and Solutions
- Lock File Not Being Removed: Ensure that the script is properly configured to remove the lock file after processing. If the lock file remains, it could prevent future executions.
- Emails Not Sending: If emails are not being sent, check the configuration of your SMTP server and ensure that the Mautic email settings are correctly configured.
