Matomo

Matomo (formerly known as Piwik) is an open source website tracking tool (like Google Analytics) written in PHP. Hosting a website tracker by yourself gives you full data ownership and privacy protection of any data collected and stored, especially with regard to data laws like the EU’s General Data Protection Regulation (GDPR).

Note

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

License

Matomo is released under the GPLv3 License.

Prerequisites

We’re using PHP in the stable version 8.1:

[isabell@stardust ~]$ uberspace tools version show php
Using 'PHP' version: '8.1'
[isabell@stardust ~]$

You’ll need your MySQL credentials. Get them with my_print_defaults:

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

If you want to use Matomo with your own domain you need to add it first:

[isabell@stardust ~]$ uberspace web domain list
isabell.uber.space
[isabell@stardust ~]$

Installation

If you want to install Matomo into a subfolder of your domain, download and unzip it in your document root:

[isabell@stardust ~]$ cd /var/www/virtual/$USER/html
[isabell@stardust html]$ wget https://builds.matomo.org/matomo.zip
[isabell@stardust html]$ unzip matomo.zip
[isabell@stardust html]$ rm matomo.zip

Now point your browser to your Matomo URL. In this example, it is https://isabell.uber.space/matomo. Follow the instructions in your browser.

You will need to enter the following information:

your MySQL hostname, username and password: the hostname is localhost and you should know your MySQL credentials by now. If you don’t, start reading again at the top.

your Matomo database name: we suggest you use an additional database. For example: isabell_matomo

Administrator (Super User) username and password: choose a username (maybe not admin) and a strong password for the super user

Name and URL of the first website you want to track with Matomo (more can be added after installation)

Best practices

auto-archive

archiving can slow down Matomo quite a bit. So if you want to have a more fluent workflow this is recommended.

enter crontab with

[isabell@stardust ~]$ crontab -e

and enter with your url (more configuration-details about cron):

# run matomo archiving outside of mysql backup hours
5 6-23,0-2 * * * /usr/bin/php /home/$USER/html/matomo/console core:archive --url=https://isabell.uber.space/ > /dev/null

Tracking

There are different ways to use Matomo for website tracking. The easiest way is to embed the provided JavaScript Tracking Code into your website. It should be added into the head section before the closing </head> tag.

<!doctype html>

<html lang="en">
<head>
  <meta charset="utf-8">
  <title>The HTML5 Herald</title>
  <meta name="description" content="Isabells Blog">
  <meta name="author" content="Isabell">

  <!-- Matomo -->
  <script type="text/javascript">
    var _paq = _paq || [];
    /* tracker methods like "setCustomDimension" should be called before "trackPageView" */
    _paq.push(['trackPageView']);
    _paq.push(['enableLinkTracking']);
    (function() {
      var u="//isabell.uber.space/matomo/";
      _paq.push(['setTrackerUrl', u+'piwik.php']);
      _paq.push(['setSiteId', '1']);
      var d=document, g=d.createElement('script'), s=d.getElementsByTagName('script')[0];
      g.type='text/javascript'; g.async=true; g.defer=true; g.src=u+'piwik.js'; s.parentNode.insertBefore(g,s);
    })();
  </script>
  <!-- End Matomo Code -->

</head>

[...]

Moreover, Matomo provides Image Tracking and the importing of server logs. Also it offers a Tracking HTTP API, which lets you integrate the Matomo Tracking for example in your PHP application.

Privacy

By default, Matomo respects DoNotTrack. As Uberspace shortens IP addresses by default, there are no additional privacy settings needed.

Nevertheless, you should update your Privacy Policy to explain how Matomo is used and what data it gathers. For this, Matomo provides a Privay Policy template.

Also, you can provide your users an Opt-Out Feature using iframes. Therefore, go to Administration >> Privacy >> Users opt-out and copy the provided HTML-Code into your website, e.g. in your Privacy Policy.

Warning

If you want to track a website outside of your uberspace, be aware that you won’t be able to place an opt-out iFrame due to the option X-Frame-Options: SAMEORIGIN which is enabled by default. This implicates a breach of the GDPR laws and should be solved otherwise. Use a solution like the official plugin Ajax Opt Out instead to serve a opt-out option for your visitors.

Updates

The easiest way to update Matomo is to use the web updater provided in the admin section of the Web Interface. Matomo will show you a hint if there is an update available.

Note

Check the changelog regularly to stay informed about new updates and releases.

Backup

Backup the following directories:

~/html/matomo/

Additionally, backup the MySQL database:

[isabell@stardust ~]$ mysqldump isabell_matomo | xz - > ~/isabell_matomo.sql.xz

Tested with Matomo 4.12.3, Uberspace 7.13, PHP 8.1

Written by: GodMod <godmod@eqdkp-plus.eu>