🔥Matomo 5 UPGRADE - A step-by-step GUIDE 🤌

TL;DR 🔍

Matomo just released their major v5 upgrade with following key improvements:

1. A transition to the frontend framework Vue.js which most notably brings a fresh new icon set
2. Improved query performance for faster reports
3. Support the latest PHP version including 8.1, 8.2 and 8.3

In total the Matomo team and contributors closed 270 tickets. All changes can be found in this diff from "Fossies".

But Upgrading Matomo - especially in a containerized environment - can be quite challenging.
We recently implemented Matomo 5 support into Glasskube and are happy to share our learnings.

We already wrote a guide about Installing Matomo on Kubernetes. This guide takes care about how to upgrade Matomo.

We Want Your Feedback! 🫶

Share your thoughts in the comments below! Let us know what topics you'd like more content on. If this guide helps, click on the cat and leave a star to support us in creating more developer-centric content. Your feedback matters!

Matomo upgrade methods

One-Click Matomo Update (Auto Update)

If Matomo is installed and operated on a single VM Matomos auto update feature can be used and the update can be triggered via the user interface. After the initial upgrade also a database migration can be performed via the UI.
Make sure to update the file permissions before starting the upgrade and revert these permission after the successful upgrade.

If Matomo is installed via Docker or in a Kubernetes cluster the update process might be a little more tricky.

Matomo Docker Upgrade

After switching to the latest Docker image make sure to use the docker exec command to open a shell inside the container and execute ./console core:update. This will start the upgrade process for a Docker based deployment.

Matomo upgrade dependencies

When upgrading Matomo it is always important to make sure that dependencies are also up-to-date. Matomo recommends the latest PHP 8.x release to improve memory efficiency and benefit from the latest security improvements.
Also, the latest version of a MySQL or MariaDB is highly recommended to increase upgrade speed by supporting index renaming and many more features.
In addition to the runtime and database it is also recommended to keep the webserver (Apache2 or NGINX) up to date - and of course all other packages and operating system itself.

When running Matomo in a dockerized environment, virtualization takes care about the runtime dependencies as the latest matomo image is based upon the php:8.2-apache base image.

Matomo upgrade errors and resolutions

After upgrading Matomo different errors can occur that need immediate resolution as your Matomo instance might not be available at the moment.

Matomo upgrade failed: File integrity check failed

The file integrity check can either be a warning inside the system check section of Matomo itself or can lead to more severe errors like Matomo not starting or throwing different Exceptions.

The root cause of this issue is that Matomo doesn't work if other files are in the working directory. If a new release of Matomo was just copied into the Matomo working directory without deleting the old files this error might occur.
The Matomo docker image uses following entrypoint script to overwrite the working directory with latest Matomo release downloaded into the /usr/src/matomo directory.

The full script can be found in GitHub matomo/docker docker-entrypoint.sh.

Matomo upgrade failed: Console not working

If the Matomo console does not produce any output your Matomo installation is corrupt. This can have multiple reasons, but most likely your there are some .php files in the working directory that do not belong to the latest release.

Make sure to clean the Matomo directory before installing the latest release.

Warning

Make sure to back up your Matomo configuration located in config/config.ini.php as it holds your configurations for example database and caching credentials.

Matomo upgrade failed: Uncaught exception

If Matomo be opened in the web browser, but an Exceptions appears in the server logs your Matomo installation is also corrupt. Again, the most likely reason for this error to occur is that the working directory is not clean.

An example stack trace can look like this:

Uncaught exception in /var/www/html/plugins/Goals/Commands/CalculateConversionPages.php line 34:
Call to undefined method Piwik\Plugins\Goals\Commands\CalculateConversionPages::addOptionalValueOption()
ERROR [2024-01-01 17:04:10] 7  Uncaught exception: Error: Call to undefined method Piwik\Plugins\Goals\Commands\CalculateConversionPages::addOptionalValueOption() in /var/www/html/plugins/Goals/Commands/CalculateConversionPages.php:34
Stack trace:
#0 /var/www/html/vendor/symfony/console/Symfony/Component/Console/Command/Command.php(65): Piwik\Plugins\Goals\Commands\CalculateConversionPages->configure()
#1 /var/www/html/core/Console.php(171): Symfony\Component\Console\Command\Command->__construct()
#2 /var/www/html/core/Console.php(133): Piwik\Console->addCommandIfExists('Piwik\\Plugins\\G...')
#3 /var/www/html/core/Console.php(87): Piwik\Console->doRunImpl(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#4 /var/www/html/vendor/symfony/console/Symfony/Component/Console/Application.php(126): Piwik\Console->doRun(Object(Symfony\Component\Console\Input\ArgvInput), Object(Symfony\Component\Console\Output\ConsoleOutput))
#5 /var/www/html/console(32): Symfony\Component\Console\Application->run()
#6 {main}

`

Matomo 5 Plugin compatibility

Before upgrading to version 5 make sure that your plugins already support the latest Matomo release.

The best way to check plugin compatibility is their Matomo On-Premise Marketplace

If a plugin is not compatible it is recommended to deactivate it before the upgrade via the console:

./console plugin:deactivate ProblematicPlugin

Matomo 5 Upgrade via the Glasskube Kubernetes Operator

If Matomo was installed in Kubernetes via the Glasskube Kubernetes Operator your current custom resource definition probably looks similar to:

Matomo.yaml

yaml
apiVersion: glasskube.eu/v1alpha1
kind: Matomo
metadata:
name: matomo
spec:
host: stats.mycompany.eu


Warning

Before upgrading to the latest Matomo version make sure that at least Glasskube Operator v0.13.10 is installed as it introduced Matomo 5 Support.

An explicit version needs to be added in order to upgrade to the latest version.

Matomo.yaml

yaml
apiVersion: glasskube.eu/v1alpha1
kind: Matomo
metadata:
name: matomo
spec:
version: 5.0.0 # Checkout https://github.com/glasskube/images/releases for the latest release
host: stats.mycompany.eu


After changing your custom resource you need to execute kubectl apply -f Matomo.yaml. The Glasskube operator will automatically perform the upgrade and all database migrations.

What happens under the hood during the Matomo 5 upgrade on Kubernetes?

Glasskube uses init containers to perform all the tasks that would have needed manual interactions like:

• Making sure necessary plugins are installed or unnecessary plugins are removed
• Syncing the latest Matomo release into the working directory and making sure to not remove your geo ip database und /tmp folder
• Perform a database upgrade if needed
• Installs an initial site if no site is yet installed
• Convert your database to utf8mb4 if it was not yet correctly initialized
• Create needed security files

The exact commands can be found in our install.sh file will be executed as in init container.

Matomo System Check

Always make sure that the Matomo system check is green and doesn't report any warnings or errors.

The system check can either be viewed as an administrator in the settings page or via the console


./console diagnostics:run


The desired state will look like:

Installing Matomo via Glasskube will help you to reach the desired system check state that no errors or warnings are present.

Conclusion

Running the latest version of Matomo can require some heavy plumbing especially if you need to take care about dependencies, backups and database upgrades, but utilizing the latest features and security features will definitely make it worth.