Installing Matomo

This post explains how to install the analytics tool Matomo in Docker containers, so basic knowledge of this technology is recommended (working with images, creating and destroying containers, viewing logs...).

What is Matomo?

Matomo is a free web analytics management tool. It has several features that set it apart from its alternatives:

• Full control over your data: you alone decide where to store the collected data and whom to share it with.
• Unbiased data, not samples of the originals.
• Specific settings to improve visitor privacy.
• Ability to import data from other services (such as Google Analytics).

Matomo offers two ways to use its services and products: using its servers and paying for that service; or hosting its products yourself on your servers (or VPS).

Getting started

As mentioned, we will use Docker to host Matomo (through docker-compose). These are the containers we will use:

• Matomo: will contain the analytics program installation.
• MariaDB, (or MySQL): the database where it will store the settings and data.
• Nginx, for the web server.

Preparing the environment

When creating the server, we will select the Apps -> Docker (Ubuntu 18.04) option. Depending on the number of users of our pages, we may need more capacity, but initially the minimum specifications will work correctly (0.5 vCores, 1GB RAM, 5GB SSD).

Several ports must be accessible to access the web interface. Basically, HTTP (80 by default) and HTTPS (443 by default) are required.

Also, before starting with Docker, we will create several folders to store data persistently, so that we do not lose data when a container shuts down

• /root/data/mariadb_matomo:

          for the DB:

• /root/data/matomo:

          for Matomo data

• /root/data/nginx_matomo_config/matomo.conf:

           for the Nginx configuration file. In this case, the following has been used as an example (without            HTTPS):

# /root/data/nginx_matomo_config/matomo.conf
upstream php-handler {
	server app:9000;
}

server {
	listen 80;

	add_header Referrer-Policy origin; # make sure outgoing links don't show the URL to the Matomo instance
	root /var/www/html; # replace with path to your matomo instance
	index index.php;
	try_files $uri $uri/ =404;

	## only allow accessing the following php files
	location ~ ^/(index|matomo|piwik|js/index|plugins/HeatmapSessionRecording/configs).php {
		# regex to split $uri to $fastcgi_script_name and $fastcgi_path
		fastcgi_split_path_info ^(.+\.php)(/.+)$;

		# Check that the PHP script exists before passing it
		try_files $fastcgi_script_name =404;

		include fastcgi_params;
		fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
		fastcgi_param PATH_INFO $fastcgi_path_info;
		fastcgi_param HTTP_PROXY ""; # prohibit httpoxy: https://httpoxy.org/
		fastcgi_pass php-handler;
	}

	## deny access to all other .php files
	location ~* ^.+\.php$ {
		deny all;
		return 403;
	}

	## disable all access to the following directories
	location ~ /(config|tmp|core|lang) {
		deny all;
		return 403; # replace with 404 to not show these directories exist
	}
	location ~ /\.ht {
		deny all;
		return 403;
	}

	location ~ js/container_.*_preview\.js$ {
		expires off;
		add_header Cache-Control 'private, no-cache, no-store';
	}

	location ~ \.(gif|ico|jpg|png|svg|js|css|htm|html|mp3|mp4|wav|ogg|avi|ttf|eot|woff|woff2|json)$ {
		allow all;
		## Cache images,CSS,JS and webfonts for an hour
		## Increasing the duration may improve the load-time, but may cause old files to show after an Matomo upgrade
		expires 1h;
		add_header Pragma public;
		add_header Cache-Control "public";
	}

	location ~ /(libs|vendor|plugins|misc/user) {
		deny all;
		return 403;
	}

	## properly display textfiles in root directory
	location ~/(.*\.md|LEGALNOTICE|LICENSE) {
		default_type text/plain;
	}
}

# vim: filetype=nginx

chown -R www-data:www-data data/matomo/

chown -R www-data:www-data data/mariadb_matomo/

In some cases this solution does not work either; if so, you can give the folder permissions of 0755 (or 0777 if it still does not work). It may also be because the disk is full.

Docker-compose

We will use the docker-compose tool. To do so, we can use these configuration options (YML format):

{yml}
version: '3'

services:
  db:
    image: mariadb
    command: --max-allowed-packet=64MB
    restart: always # so it restarts if it crashes at any point
    volumes:
      - /root/data/mariadb_matomo:/var/lib/mysql # directory where DB data will be stored persistently
    environment:
      - MYSQL_ROOT_PASSWORD=miContraseniaComplicada # root password
      - MYSQL_USER=matomo # DB user
      - MYSQL_PASSWORD=contraseniaUsuario # password of the user specified on the previous line

  app:
    image: matomo:fpm-alpine
    restart: always
    links:
      - db # communication with the DB
    volumes:
      - /root/data/matomo:/var/www/html # directory where Matomo data will be stored persistently
    environment:
      - MATOMO_DATABASE_HOST=db # the name we gave the DB connection
      - MATOMO_DATABASE_USERNAME=matomo # DB user
      - MATOMO_DATABASE_PASSWORD=miContraseniaComplicada # password of the previous user

  web:
    image: nginx:alpine
    restart: always
    volumes:
      - /root/data/matomo:/var/www/html:ro # directory where web server data will be stored persistently
      - /root/data/nginx_matomo_config/matomo.conf:/etc/nginx/conf.d/default.conf:ro # directory containing the web server configuration
    ports:
      - 80:80 # http
      - 443:443 # https
      

We save this file as `docker-compose.yml` in whichever folder we want and run `docker-compose up -d`. It will then start downloading the necessary images, and if everything has gone normally, it will display a message similar to the following:

Creating network "data_default" with the default driver
Creating data_web_1 ... done
Creating data_db_1  ... done
Creating data_app_1 ... done

We can now access it through our preferred browser. It is best to disable any ad blocker, as it may interfere with the program.

Completing the installation

If everything went well, a screen like the following should appear to finish the installation process:

When we click the button, it will perform a system check, warning us that we are not using HTTPS and that it is recommended. To enable it, you must obtain an SSL certificate (Let's Encrypt, for example) and then click the link shown. If you do not do this in that order, the application will crash.

Next, it will ask for the DB configuration. The user we created must be able to create tables; otherwise, use the root user.

Once the tables have been created, we will proceed to configure Matomo, create the administrator user and configure email (we must enable the outgoing SMTP option in Clouding so that it can send us emails)

If everything went well, it will ask for the address of the website for which we want statistics. You can change it later and add others.

The next screen will give us the JavaScript code to insert into our website:

And Matomo is now installed :)

Configuration

After completing the installation process, we can access our VPS website and will see a login screen, where we must enter the information we provided earlier.

Once this is done, it will show the control panel, where we can view metrics once the first visitors have accessed our website. The navigation menu has several options, which are explained in the Matomo documentation. 

Adding new sites

From the "Todos los sitios de internet" section, you can add a new website for which to obtain statistics (you can also do this for apps, iOS or Android for example; see SDKs). It will give us JS code like the code we entered during installation, which we must insert into the website.

GeoIP

This service lets us geolocate visitors to our website based on their IP. It is not very accurate at times, but works quite well at the regional level. To do this, click the gear at the top and then Sistema -> Localización.

By default, the system estimates the country of origin from the language used. This estimate is quite inaccurate, so we will change it to GeoIP 2 (PHP), since nothing else needs to be installed on the server; the change is automatic.

Then, in the next section, you must choose the database link containing the location data. Matomo uses the [MaxMind](http://www.maxmind.com/?rId=piwik) service, which provides city-level databases. Data on ISPs and other information requires payment for that service.

Excluding our own visits

There are several main ways to exclude our visits to the configured websites. Here we will explain two of them, but you can see all of them under Configuración -> Sitios de internet -> Configuración:

1. We can specify an IP for which we do not want to save metrics. This is the least recommended option, since IPs are usually dynamic, so we may have to change this parameter several times.
2. Another option is to download a Cookie to exclude our metrics. The drawback is that it must be downloaded for each device we want to exclude. To do this, go to Configuración -> Personal -> Configuración, and in the last section you will find the link to download the cookie: