How to upgrade our Matomo (formerly Piwik) web analytics system to version 4.x.

botond published 2020/12/15, k - 09:30 time

Content

  1. page: Settings before updating Matomo, update
  2. page: Post-update settings, geolocation

 

The 1. page content

 

Introductory

A Matomo (formerly Piwik) web analytics system is a high-quality statistical tool that provides us with a detailed and comprehensive picture of our website traffic. I previously made a description of About installing and deploying Matomo software on your own server, and in this tutorial we will review how to upgrade your web analytics system to the recently released major version 4.x. The web statistics program also contains many new features, but in this description we do not focus on these, but we satisfy the software requirements for the new main version so that the system can continue to operate stably.

The Matomo system was previously used in Debian 9 Stretch is the perfect server for version 1.0 I installed it, so in this description the update to this is done Matomo installation I make it as a sequel. Matomo may be upgraded under other system conditions, but in such cases the upgrade process may be different from that described here.

This description is intended primarily for those who have previously installed the Matomo system and it has since become obsolete on their server, so a few things need to be replaced to keep Matomo running.

 

 

Settings before updating Matomo

When we enter the interface of the Matomo web analytics system, we see a yellow message warning of the latest version. On which, when we hover the mouse, write our current version:

Matomo (Piwik) - New version available

It has been installed on this Debian9 server for a very long time, I haven't updated it since, so we need to update several versions here. For now, don't click on the update, but click on the gear in the upper right corner, then you will get to the general settings page, where the system will also display status info, let's look around first:

Matomo (Piwik) - Status page

The yellow panel at the top warns us that the server is currently in use PHP Version 7.0 will no longer be supported in the next version (3.14.x), so you will need to use at least PHP 7.1 for the program to work. We stop at this point, because without it we can no longer use our Matomo web analytics system. This Debian 9 (Stretch) server only has the default PHP 7.0 and one hand-translated 5.6.40, so we need to install another version of PHP as well.

Because this is a version of Matomo running on a very old installed server that is still running under PHP 7.0, the Matomo updater cannot upgrade immediately to the latest version 4.x, but only to an intermediate version 3.14.x, for which PHP Write version 7.1 as a basic requirement. However, it is a good idea to switch to a much newer PHP so that you do not need a multi-step update, but the latest 4.x update goes up right away. Matomo 4.x will require at least PHP 7.2.5 to run, so it is a good idea to switch to the current fresh version of PHP 7.2 at least.

Of course, for other server configurations, there may be different situations where you would not normally need to upgrade from such an old version if you keep your software up to date on a regular basis. I'm going on in this description as a continuation of the previous Debian 9 perfect server, which is a very old installation, so here's why it's needed now

 

Installing PHP 7.4

If we are installing another PHP, I will choose version 7.4 here, so I can plan for the longer term in terms of the virtual server uploaded to the site, because I don't know in advance when I will continue this Debian 9 perfect server line, even now I only had to bring it up again because of the Matomo update. And if I’m already working on this server, I’ll update everything to the latest in it so that the newer server version I upload is as comfortable to use as possible.

The main version of PHP 8 has already been released, but it is currently not supported by few systems (2020-12), so it would be too early to install it now, which will be discussed in another description.

Of course, we can also choose PHP 7.2 or 7.3, I will move on to 7.4 here for the reasons described above.

There are several ways to install the newer PHP, the easiest is to follow my previous description, in which custom PHP versions have been installed on a Debian 9 LAMP server. Here as described configure the deb.sury.org repository, and then install it first basic packagesand then a PHP 7.4 packages, or which PHP version you want. These PHP package selections are already well-proven assemblies, and the components in them result in massive PHP installations on which we can run anything. So feel free to install all of the PHP version packages we have selected.

When upgrading PHP packages, there may be retained packages, and it is a good idea to update them as many of them contain security updates for Debian 9. Learn how to install withheld packages here.

When you are ready to install the newer PHP, you can check the version from the command line:

Check PHP version 7.4

So here is a fresh and crisp version of 7.4.13.

Setting a custom PHP version in the ISPConfig interface (optional)

This section is optional, nor is it relevant to this description, but if you have already installed newer versions of PHP, you may want to configure them in the ISPConfigban is. I will not go into detail about this now read here. Accordingly, I configured PHP 7.4 as a custom PHP version on this server in the ISPConfig interface, as well as the hosting space that contains the only WordPress website.

ISPConfig3 - Custom PHP version 7.4 configured

So now you can now access the manually compiled versions of PHP 5.6.40, the default 7.0 (which is not shown here), and the 7.4 just configured 5.6.40. Of these, the manually translated version 7.0 is not updated, the other two are, or as long as branch XNUMX receives the security updates.

 

 

However, we are not ready with this yet, we still have to configure Matomo to run the new PHP.

 

Configure PHP-FPM Pool

When installing Matomo, we set it to the correct one PHP-FPM the system should run in pool, so we can operate it with completely independent settings from all other websites, Apache configurations, from phpMyAdmin, etc. THE I wrote about PHP-FPM pools here earlier. However, the installation was done with PHP 7.0, so the Matomo web analytics system was also included in a PHP 7.0 FPM pool. Therefore, we now need to migrate this pool to the newly installed PHP 7.4.

Of course, let's make improvisations here with our own old and new PHP versions, if they differ from the setting presented here.

Move and modify PHP-FPM configuration

Let's log in first rootthen make sure that our Matomo system is running in the pool we think is:

systemctl status php7.0-fpm.service

Check Matomo PHP-FPM pool

If we see our matomo processes, we are in the right place. Then move the previously configured PHP-FPM pool configuration for the Matomo (Piwik) web analytics system from the old PHP version directory to the new one:

cd /etc/php/7.0/fpm/pool.d/
mv matomo.conf /etc/php/7.4/fpm/pool.d/

Move PHP-FPM pool

Here, too, we use the .conf filename we used earlier.

Then let's open it dwarfto edit with:

nano /etc/php/7.4/fpm/pool.d/matomo.conf

Here's a single line fix:

[...]
listen = /run/php/php7.0-matomo-fpm.sock
listen = /run/php/php7.4-matomo-fpm.sock
[...]

Let's fix the name of the socket file from our old PHP version again. This is the front line. Leave everything else intact and save.

Modify the Apache configuration

Modify the Matomo Apache configuration:

nano /etc/apache2/conf-enabled/matomo.conf

Matomo Apache configuration fix

And in this, fix the name of the socket file:

[...]
                        SetHandler "proxy:unix:/run/php/php7.0-matomo-fpm.sock|fcgi://localhost"
                        SetHandler "proxy:unix:/run/php/php7.4-matomo-fpm.sock|fcgi://localhost"
[...]

Do not change anything else, then save this as well.

Here you can enter essentially any name, just important to use the same in both places. As you specify a file name in the pool configuration, PHP-FPM creates the socket file with a name that will then be used by the Apache configuration to connect to the matomo user specified in the pool. So if we had left them in the name of the old PHP, the whole thing would still work, it is just important to always be precise, so it remains clear to ourselves later what, why we did it, once we have to touch on something, as we do now. we could easily find our previously created pool.

Restart services and check pool

 

 

Once we are done so far, restart the services in the correct order.

Restart the old PHP FPM first to disconnect the old pool, then the New PHP FPM, and finally Apache:

systemctl restart php7.0-fpm.service
systemctl restart php7.4-fpm.service
systemctl restart apache2.service

That's how everything falls into place. You can then check the FPM pool of your new PHP instance:

systemctl status php7.4-fpm.service

PHP 7.4 FPM pool check after restarting services

Our matomo pool has also been ported to PHP 7.4.

(And the processes in web1 belong to the recently configured WordPress web host, so that web host already runs with this PHP as well)

Then, if we refresh the Matomo status page, we can already see the result there:

Check Matomo (Piwik) status after configuring the new PHP

The top yellow warning has disappeared and the PHP version is already 7.4.13. However, the upgradeable version in the upper right corner is still 3.14.1, so you don't "see" the latest 4.x version yet.

Log out and log back in again.

If you don't see the icons in the upper right corner, like they don't show up for me right now, change the control panel URL in your browser's address bar as follows:

https://www.wordpress.vm/matomo/index.php?module=Login&action=logout

Here, of course, replace your own Matomo URL, and then append the appropriate index.php sections.

Since this update is now from an old Matomo version to the latest one, PHP notices and deprecated also PHP warnings, because this previous version (3.11.0) currently running does not yet support PHP 7.4. However, I don't want to upgrade in several steps, so I immediately installed PHP 7.4 to update Matomo. So here are some bugs and other weird operating anomalies in the pre-upgrade version, but after that our web analytics system will work fine. Visually, it’s not the most beautiful execution, but we save a lot of time if we don’t update the Matomo system and PHP in several steps.
Of course, all this does not happen if we only upgrade from one previous version to the new one, or if we do not immediately use PHP 7.4 to upgrade to an old version.

Immediately after logging in, we find ourselves in the usual statistics:

Matomo home page with some bugs

Here, the button to upgrade to 4.0.5 appears at the top right. And of course minor bugs on the site, for me these are for the reasons mentioned above. Here you can still jump to the Admin page before upgrading. If we have a right gear above, then if we don’t, with the URL pattern below and our own Matomo access:

https://www.wordpress.vm/matomo/index.php?module=CoreAdminHome&action=home

Matomo Admin page with a deprecated warning

Here we see a deprecated warning already mentioned above. Of course, this is probably only the case with me, but if someone else updates the system like this, you don't have to be scared of it.

After this, the upgrade of the Matomo web analytics system can start.

 

Upgrading Matomo to version 4.0.x.

 

 

Click the top right update button. You will then be taken to an information panel informing you that we can update it automatically or manually with the downloaded package. Also write that some 3rd party plug-ins may not be compatible with the new version of Matomo yet. They will be updated from their marketplace if they know, but if they are not, they will be disabled after the update:

Matomo update information

Here, click Automatic Update, as we have previously updated our Matomo (Piwik) web analytics system.

Then, after a little reload, I tossed an Internal Server Error (500) page, which I had to re-enter by pressing reload. After logging in, the update will continue. Of course, this is also only the case if you need to upgrade multiple versions at once and do all this with PHP 7.4. So normally we get the database update page right away, as is usual with other updates (for example, I went to the server without any problems):

Matomo database update

Matomo database update

You need to update quite a few database tables here, so be informed that if you have a lot of data (e.g. a lot of measured web pages or high-traffic pages), the update may take a long time, so the web run time may be short, so use the command line update. Of course, this is done with the matomo user, if we set up a separate user during the installation of Matomo:

php /opt/matomo/console core:update

And if you don't have a lot of data, you can use the green button at the bottom of the page to continue the update. I will move on with this. If you’re done and everything went well, you’ll get an information page like this:

Matomo upgrade successful

Click on the "Go to Matomo" link at the bottom of the page. Then we need to log in again. After logging in, we will enter the usual statistical section:

Matomo home page with the latest version

Here, as you can see, the system appears without error. Click on the gear:

Matomo admin page

This will bring up the Admin page, where there are no more PHP errors either, because as you can see, Matomo version 4.0.5 is already working, which is already compatible with PHP version 7.4.

As I wrote above, this wasn’t the nicest implementation - upgrading multiple versions at once, which I started with PHP 7.4 - but as you can see, our Matomo web analytics system is alive and well, and I saved a lot of time in the middle (7.2 ) By installing and configuring PHP. Of course, those who upgraded to PHP 7.2 didn't get these little bugs.

However, the story is still not over here because we still have to meet Matomo’s system requirements for it to work flawlessly.

 

 

A next page we will continue to provide system requirements after updating Matomo.

 

 

Navigation

This description consists of several pages: