Matomo¶

License: GPLv3

This guide is tested with Matomo 5.10.1 on Uberspace 8.0.0. We can't guarantee it to work with newer versions.

Matomo is a free and open-source web analytics platform written in PHP.

Note

For this guide you should be familiar with the basic concepts of:

Prerequisites¶

We're using PHP in version 8.4 and MariaDB.

Check your PHP version:

[isabell@moondust ~]$ php -v
PHP 8.4.16 (cli) ...

Check your MariaDB client version:

[isabell@moondust ~]$ mariadb --version
mariadb from 12.2.2-MariaDB, client 15.2 for Linux (x86_64) using readline 5.1

You'll need your MariaDB credentials during the Matomo web installer:

[isabell@moondust ~]$ my_print_defaults client
--default-character-set=utf8mb4
--user=isabell
--password=MySuperSecretPassword

Create a new database for Matomo:

[isabell@moondust ~]$ mariadb -e "CREATE DATABASE ${USER}_matomo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

You can check if the database was created:

[isabell@moondust ~]$ mariadb -e "SHOW DATABASES;"

Installation¶

Go to your web document root:

[isabell@moondust ~]$ cd /var/www/virtual/$USER/html/

Download and extract Matomo:

[isabell@moondust html]$ wget https://builds.matomo.org/matomo.zip
[isabell@moondust html]$ unzip matomo.zip
[isabell@moondust html]$ rm matomo.zip

The zip file also contains a local HTML installation file. You can remove it from your document root:

[isabell@moondust html]$ rm "How to install Matomo.html"

Matomo is now installed in the matomo subdirectory and available at:

https://isabell.uber.space/matomo/

Open this URL in your browser and follow the web installer.

Use the following database settings:

Database Server: 127.0.0.1
Database Login: isabell
Database Password: MySuperSecretPassword
Database Name: isabell_matomo
Table Prefix: matomo_
Adapter: PDO\MYSQL

Note

Matomo may be blocked by browser ad blockers, tracking protection features or DNS-based blockers.

If the Matomo interface does not load correctly or tracking does not work, disable these blockers for your Matomo URL.

Installation path¶

This guide installs Matomo into a subdirectory:

https://isabell.uber.space/matomo/

If you want to install Matomo directly into your document root, move the contents of the extracted matomo directory into /var/www/virtual/$USER/html/ instead.

If you want to use a separate domain or subdomain, add the domain to your Asteroid first and use that URL during the Matomo web installer and later for the archive cronjob.

For example:

https://stats.example.com/

or, when using the subdirectory from this guide:

https://stats.example.com/matomo/

Security files¶

During the system check Matomo may show a warning about PHP-FPM and .htaccess rules for .php files.

On Uberspace 8 this warning can be expected because PHP runs via PHP-FPM. You can continue the installation if this is only a warning.

After the installation, create or update Matomo's security files:

[isabell@moondust ~]$ php /var/www/virtual/$USER/html/matomo/console core:create-security-files
Done.

Check that sensitive files are not publicly readable:

[isabell@moondust ~]$ curl -I https://isabell.uber.space/matomo/config/config.ini.php
HTTP/2 403

The configuration file must not be returned as plain text. If sensitive files are publicly readable, stop and contact the Uberspace support before using the installation.

You may need to run core:create-security-files again after updating Matomo.

Configuration¶

Matomo recommends running report archiving with a cronjob instead of relying on browser-triggered archiving.

Test the archive command manually:

[isabell@moondust ~]$ php /var/www/virtual/$USER/html/matomo/console core:archive --url=https://isabell.uber.space/matomo/
INFO      ...
INFO      done: 2 req, no error

Edit your crontab:

[isabell@moondust ~]$ crontab -e

Add the following cronjob:

5 * * * * php /var/www/virtual/$USER/html/matomo/console core:archive --url=https://isabell.uber.space/matomo/ > /dev/null

Check your crontab:

[isabell@moondust ~]$ crontab -l
# UBERSPACE: this config sets a minimal delay on cronjobs so the load is more balanced
RANDOM_DELAY=3

#--- put your cronjobs below this line ---
5 * * * * php /var/www/virtual/$USER/html/matomo/console core:archive --url=https://isabell.uber.space/matomo/ > /dev/null

After setting up the cronjob, disable browser-triggered archiving in Matomo:

Administration → System → General settings

Updates¶

Note

Check the Matomo changelog regularly.

Log in to Matomo and use the built-in updater.

After an update, run:

[isabell@moondust ~]$ php /var/www/virtual/$USER/html/matomo/console core:create-security-files

Then check again that sensitive files are not publicly readable:

[isabell@moondust ~]$ curl -I https://isabell.uber.space/matomo/config/config.ini.php
HTTP/2 403

Backup¶

A Matomo backup should include the application files and the database.

Create a database dump:

[isabell@moondust ~]$ mariadb-dump ${USER}_matomo > ~/matomo.sql

Create an archive of the Matomo files:

[isabell@moondust ~]$ tar -czf ~/matomo-files.tar.gz -C /var/www/virtual/$USER/html/ matomo

Download both files and store them safely.