Running the latest version of Matomo can require some heavy plumbing especially if you need to take care about dependencies.
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.
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.
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.
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.
After upgrading Matomo different errors can occur that need immediate resolution as your Matomo instance might not be available at the moment.
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
The full script can be found in GitHub
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.
Make sure to back up your Matomo configuration located in
config/config.ini.phpas it holds your configurations for example database and caching credentials.
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
#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()
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
If Matomo was installed in Kubernetes via the Glasskube Kubernetes Operator your current custom resource definition probably looks similar to:
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.
version: 5.0.0 # Checkout https://github.com/glasskube/images/releases for the latest release
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.
Glasskube uses init containers to perform all the tasks that would have needed manual interactions like:
utf8mb4 if it was not yet correctly initialized
The exact commands can be found in our
install.sh file will be executed as in init container.
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
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.
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.
Easily and scale your IT infrastructure while deploying applications quickly and securely with our cloud native technology solutions.