Important changes to the Mautic install and upgrade process

By Ruth Cheesley · PUBLISHED February 25, 2022 · UPDATED March 02, 2022

The biggest problems we see in the Mautic Community forums tend to be around installing and updating Mautic. Difficulties with permissions, incomplete updates, and all the associated problems that this causes. This can be further compounded by plugins which may be incompatible with newer versions of Mautic, causing it to crash on update.

Over the last year the Install and Upgrade Initiative team have been working closely with the Product Team on investigating how to bring more stability to the installation and upgrade process of Mautic. We are now beginning to introduce some changes with the ultimate goal of having a rock-solid, stable install and upgrade workflow for Mautic which works as well for single Mautic instances as for managing Mautic at scale.

Coming soon

Deprecating current installation and upgrade methods

Since Mautic 2.0 we have been advising Mautic users to update at the command line, now we are going to make it a requirement.

With the 4.2.0 release of Mautic, you will start to see warnings if you are using the update feature within Mautic itself (often referred to as ‘in the user interface’ [UI]), telling you that this has been deprecated and will be completely removed in Mautic 5. 

A screenshot of the update screen with a warning that UI-based updates are going to be deprecated in Mautic 5

The reason for this will be evident to anybody who has tried to use the update feature within Mautic with anything other than a test installation - during the update process, a lot of intensive tasks have to be executed which can take quite some time with a large number of contacts. This will often cause the process running on the server to be terminated due to the hosting environment being incapable of completing the tasks with the available resources. This is the number one issue where updates fail and cause Mautic to crash, leaving users extremely frustrated.

From Mautic 5, you will no longer be able to update Mautic from within the user interface, and will have to update following specific commands at the command line.

We do appreciate that for some users of Mautic, this adds an extra layer of complexity, however we believe that the benefits outweigh the many difficulties that users of Mautic experience when attempting updating within the user interface.

Improving in-app guidance to users on how to update

While we will be removing the ability to update in the user interface, we will still be alerting users when a new version of Mautic is available. There will be detailed information provided if their environment doesn’t support updating (for example if a higher version of PHP is required or plugins need to be updated), and a clear overview of what is included in the new version of Mautic.

We will be providing easy to follow, step-by-step instructions for users to follow at the command line in order to update their Mautic instance.

Composer as the supported method for installing and updating Mautic and third party plugins

Since Mautic 4.0 it has been possible to fully manage Mautic with Composer thanks to the work of the Composer Initiative, which brings Mautic in line with many other PHP applications who already use this technology for installing and updating software.

With the introduction of Composer 2, the process is even more efficient and robust, and many Mautic users have reported great success in using Composer to manage their Mautic installations.

With the removal of the UI-based upgrade in Mautic 5, we will also be switching to using Composer as the official way to install and update Mautic. This also has the added benefit of unlocking the ability to manage plugins within the Mautic Marketplace, which is dependent on Composer.

From Mautic 4.2 there is a new setting which you can enable to tell Mautic that you are managing it through Composer, which will disable the built-in updating system, and enable you to manage plugins within the Marketplace.  With this setting enabled, users will see a message warning them that they are not able to update in the user interface.

Screenshot of the update screen showing a warning that the instance is managed by Composer and can't be updated in the user interface.

Improving documentation

With the changes above we recognize the need to improve the documentation we have available, both within the application (as mentioned above) but also in the end-user and developer documentation.

The end-user and developer documentation are currently undergoing a review, update and re-platform to Read the Docs which will enable us to maintain versioned documentation related to different Mautic versions, and to translate the documentation into other languages using Transifex. We would welcome contributors who would like to help with this task, even if you only have a small amount of time - we have lots of small tasks that need to be done. Please join us in #t-education on Slack if you would like to get involved!

We will also be greatly extending the articles we have in our Knowledgebase and moving to a more effective platform, which will enable community members to submit new articles for review, and also provide a much more intuitive experience. We hope that this will include regularly updated tutorials on how to install Mautic on all the popular hosting platforms, and the development of one-click installers.

Future plans

Automatic updates

With the changes above, we are planning in the future to enable automatic updates as a feature which can be enabled by an administrator. Bug fix releases are generally safe to update automatically as they do not include any major changes, new features or significant variations of existing features.

This will not be an option until at least Mautic 5.0, and even then, will require a Composer-managed installation due to the underlying functionality required.

Decoupling plugins and enabling selection during installation

With the changes we are making and the introduction of the Mautic Marketplace, we are planning to fully decouple plugins and integrations from the core of Mautic.

This means that when you install Mautic, you will start with the absolute basics which are required for Mautic to operate - making Mautic installations very streamlined by only including the features that you specifically need for your instance.

During the installation process, the user will be given the opportunity to select other features, functionality or integrations that might be helpful, and to install them. For example, you might want to install the plugin to integrate with your CRM system, or to use a specific third party email provider.

We have started the work on this already by separating the individual plugins out into their own repositories as part of the Composer Initiative, which are currently acting as read-only ‘mirror’ repositories.

The next steps will be to fully isolate each plugin by removing any inter-dependencies, and then to develop the experience within the installation process to include core plugins which are required, and enable the user to select from the marketplace any third party plugins they might need.


I’m pleased to see that we’re starting to make some headway in addressing some of the fundamental problems that people experience when they are installing and updating Mautic, and am looking forward to hearing your thoughts on our future plans for Mautic. Please do reply in the companion forum thread if you have any comments!

4 Responses

dbayer's avatar

September 20, 2023

Does this mean, there will no longer be a Docker Install method?

escopecz's avatar

The opposite actually. It will be simpler to maintain the Docker image.

dbayer's avatar

September 22, 2023

Thanks for the info.
Is there a docker-compose file we can try during the alpha phase?

escopecz's avatar

I’m not aware of any such project, but I haven’t searched for it. Perhaps you want to kickstart it? There is the DDEV folder that might be useful for inspiration.