Based on Debian 11 "Bullseye" environment.


Matomo is an access analysis software. This can capture the visitor information with small javascript. As the official page says, this is an alternative to Google Analytics.
(In case javascript can't be implemented, a small picture file or Nginx log can be used instead.)

Matomo provides cloud service as well as On-Premise installation. Cloud service will cost you some, but it offers additional services and analytics.
Here I write the case with On-Premise installation for full control of the data.
Since Matomo official documentation explains everything, here I describe only small tips or additional information.

Matomo requirements

Here are some additional explanations for the official guide.

PHP extensions

As written on the requirements page, some extensions are required. They all are available as Debian packages.

# apt install php-curl php-gd php-cli php-xml php-mbstring
  • If you followed the articles on this site, you have already installed php, mysql-server, and php-mysql packages.

MariaDB user

Setup a user and a database for Matomo.

# MariaDB
> CREATE USER 'matomo'@'localhost' IDENTIFIED BY 'password';
> GRANT ALL ON matomo.* TO 'matomo'@'localhost';


Matomo installation

When installing to the server, the alternative way described in the document is the easiest.
For example, at /var/www

# wget && unzip
# chown -R www-data:www-data matomo
  • It generates 'How to install Matomo.html' in the current directory. This is a redirect to the installation document so you can safely delete it.
  • Of course, can be deleted once you complete the installation.
  • When you see Matomo web installation, the install will show commands always starting from "chown www-data:www-data..." To omit this, change the ownership of all files under matomo.

Nginx configuration

Since Matomo is written in PHP, please refer to the PHP enabled configuration in the Nginx page.

Matomo set up

Access the URL to see web set up screen. The UI is very kind and easy to understand.

  • System Check shouldn't have any missing functions or extensions.
  • Put the database information you just prepared above
  • Super User is Matomo web admin. Not the server root or Database user.

At the setup, you can get the javascript tracking code. Add the code to every page for the analytics.
(The code is available from the Matomo config and you can customize them.)

User ID from Vouch

If you have User ID (mail address, name, login name etc) on the HTTP header, Matomo can use it to count the Unique Visitors. (See details for the official document.)
In the case of Vouch Proxy, Vouch can send the user name as HTTP header.

For example Ruby on Rails, nginx should have the following reverse proxy setting.

location @app {
    proxy_pass http://localhost:3000;
    proxy_set_header Remote-User $auth_user; # This line sets the header "REMOTE-USER"
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Ssl on;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-Host $host;

Adding the following line to the app/views/application.html.erb will send the User ID to Matomo.

_paq.push(['setUserId', "#{request.env["HTTP_REMOTE_USER"]}"]);

Update History


  • Add requirements section
  • Add some notes about Matomo setup


  • Add section: User ID from Vouch