How to Install Matomo Web Analytics Tool on Debian

Matomo, formerly Piwik, is a free, open-source web analytics software tool. It is designed to provide you with key insights into your website’s visitor behavior and to help you understand the data collected to make informed decisions. Matomo also includes a Super Search feature for quick, simple, and automated data search across multiple websites.

Matomo provides several reports such as daily, weekly, and monthly visitors stats; top referring sites; social media stats like Facebook advertising campaign performance or Twitter follower growth; visitor demographics and geographical location info, etc.

It also offers a detailed analysis of your visitors’ behavior on your site—their actions and engagement time spent on pages—in order to see what works well for you or what could use some improvement.

Matomo is perfect for service providers like web agencies, developers of eCommerce websites, and blog owners to analyze visitor behavior on the website. It works along with almost every common CMS and other content management system (CMS) like WordPress, Drupal, or Joomla.

Matomo is written in PHP and fully compatible with Apache, Microsoft IIS Web Server, or Nginx. It uses MySQL or PostgreSQL to store data on a database server and can be used, according to its own website, “along with most popular programming languages”. Matomo also supports real-time analytics with real-time visitor tracking. In addition, Matomo supports various types of tracking tags for remarketing campaigns. Matomo supports mobile app install tracking and mobile app tracking for Android and iOS applications.

Matomo is a must-have data collection tool for monitoring and enhancement of online lead generation campaigns, user interaction analysis, and website performance analysis.

But you’re trying to install matomo web analytics on Debian but it doesn’t seem to be working. If you read through the article below, you will find a lot of useful and easy tips from experienced users who have successfully installed Matomo on Debian. You will learn how to install matomo in a way that works for your unique environment.


In order to install Matomo on Debian, you need to have:

  • A server running a fresh instance of Debian 10 or Debian 11. While Matomo can scale to measure multi-million page views, it is recommended to start with a small instance as a test environment. A minimum of 4GB RAM, 50GB of free disk space are recommended on the server.
  • A non-root user with sudo privileges to run commands as root. You can learn how to create a user account here.
  • A fully qualified domain name (e.g.: pointed to your server’s IP address.

Updating the Debian Software Packages

First, you need to update the system before executing any software installation command on your Debian box. This ensures that all system packages are fully up-to-date.

sudo apt update && sudo apt upgrade -y

Update packages

Installing Apache Web Server

Matomo required a LAMP (Linux, Apache, MySQL( or MariaDB), and PHP) stack to run on a server. Apache is one of those elements of the stack. Apache HTTP Server is one of the most popular web servers with millions of downloads and a wide range of features. The Apache HTTPD Web Server is a powerful tool for hosting websites and other server-based applications. It is a robust, flexible, and highly customizable platform for developing dynamic internet sites at any scale that reaches more than 50 percent market share.

You should use the free Apache web server with Matomo (formerly Piwik) if you already have it running on your system, or you wish to configure it in a specific way, or you have a complex network environment.

Run the following command to install Apache on your system. On Debian, the apache2 program provides the Apache HTTP Server (httpd). The apache package contains the programs that are needed to configure an Apache server. On Debian, the apache2-utils program provides several utilities for use with the Apache HTTP Server (httpd).

sudo apt install -y apache2 apache2-utils

Install Apache web server

Once the installation completes, start the Apache service so that it can be used by other programs.

sudo systemctl start apache2

Run the following command to check whether Apache is running or not.

sudo systemctl status apache2

If you see the following output, then Apache is running on your system:

Check Apache status

You can request a web page from the Apache server to check that it is working correctly.

When you open a page in your browser, the HTTP headers sent from the webserver to your computer include a lot of information about the content of the page.

For example, in the HTML <meta> tag you can find a header named “Content-Type”, which contains the character encoding being used on that page. At this point, you can only see the default welcome page of Apache, as shown below.

Apache default page

Install MariaDB Database Server

MariaDB is a powerful, multi-threaded, multi-user, and robust SQL (Structured Query Language) server. It is an open-source implementation of MySQL server and a drop-in replacement for the MySQL server.

Many Matomo users are using MariaDB to save their web analytics data. Even though MariaDB is not officially supported by Matomo, it can be used as a suitable database backend for Matomo.

At a bare minimum, you will need a mariadb-server and a mariadb-client. The mariadb-server package provides the MariaDB server, which enables MariaDB to run as a service. The mariadb-client package provides the MariaDB client programs, which are based on libmysql.

Run the following command to install MariaDB Database Server on your Debian system.

sudo apt install -y mariadb-server mariadb-client

Install MariaDB

Once the installation completes, secure and optimize your MariaDB server by following this guide.

Run the following command to start the MariaDB service so that it can be used by other programs.

sudo systemctl start mariadb

Finally, run the following command to check whether MariaDB is running or not.

sudo systemctl status mariadb

If you see the following output, then MariaDB is running on your system.

MariaDB status

Installing PHP

PHP is a server-side scripting language designed for web development. It can be used to create dynamic web pages that are stored in a web server’s memory and accessed by a web browser.

Matomo Web Analytics requires PHP for various tasks, the most important being web server request logging and visitor tracking.

Run the following command to install PHP 7.3 and its modules. PHP modules are extensions of the PHP programming language. These modules are provided by external libraries that enhance or extend PHP functionality. A module is nothing more than a shared library ( .so file on Linux, .dll on Windows, or .dylib on macOS) which is loaded by the PHP interpreter at runtime. Matomo Web Analytics uses PHP modules to implement specific features which are available to Matomo (Piwik) users.

sudo apt install php -y
sudo apt install php-cli php-fpm php-json php-common -y
sudo apt install php-mysql php-zip php-gd php-mbstring php-curl -y
sudo apt install php-xml php-pear php-bcmath -y

Run the following command to check the PHP version on your system.

php -v

You will get the following output on Debian 10

PHP version check

On Debian 11, the PHP version will be PHP 7.4

Creating Database for Matomo

Matomo keeps all data inside a database. So, let’s create one.

Run the following command to log in to your MariaDB shell. At the password prompt, provide your root password and press ENTER to continue.

sudo mysql -u root -p

Login to MariaDB

Run the following command to create a new database named matomo. Your Matomo installation will use this database to store all the data.


Run the following command to create a new user named matomouser for the matomo database. Replace Password with a secure password. A user is a collection of permissions. It could be anything from creating databases and tables to checking out data or executing queries. Permissions are mostly guided by security. To achieve the best possible security, you should not give more permissions than necessary for your user.

CREATE USER 'matomouser'@'localhost' IDENTIFIED BY 'mysecurepassword';

Replace ‘mysecurepassword’ with a secure password of your choice. Run the following command to grant the matomouser user the SUPER privilege. The SUPER privilege enables a user to execute any and all statements. You will want to make sure that the matomouser can do anything it wants to do to the matomo database.

GRANT ALL ON matomo.* TO 'matomouser'@'localhost' WITH GRANT OPTION;

Run the following command to reload the databases. The FLUSH PRIVILEGES command is used to reload the grant tables, allowing currently running statements to complete normally.


Finally, exit the shell.


Create matomo user and database

Configuring Your Apache Virtual Host

A virtual host is a type of website where each site serves content from its own domain name. Virtual hosts are typically used for sites with multiple domain names but are also used to provide sites with different hostnames for load balancing.

There are several reasons why you should use a Virtual Host. In this tutorial, we will focus on the following:

  • Performance improvement
  • Security

Run the following command to create a new virtual host configuration file named matomo.conf in /etc/apache2/sites-available directory.

sudo nano /etc/apache2/sites-available/matomo.conf

Populate the matomo.conf file with thefollowing lines and save and close the file. Replace with your actual domain.

<VirtualHost *:80>

ServerAdmin [email protected]
DocumentRoot /var/www/matomo/

<Directory /var/www/matomo>
DirectoryIndex index.php
Options FollowSymLinks
AllowOverride All
Require all granted

<Files "console">
Options None
Require all denied

<Directory /var/www/matomo/misc/user>
Options None
Require all granted

<Directory /var/www/matomo/misc>
Options None
Require all denied

<Directory /var/www/matomo/vendor>
Options None
Require all denied

ErrorLog ${APACHE_LOG_DIR}/matomo_error.log
CustomLog ${APACHE_LOG_DIR}/matomo_access.log combined


Run the following command to disable Apache default configuration file and enable your matomo configuration file.

sudo a2dissite 000-default.conf is basically disabling the default site which comes with apache installation, hence to make sure that no one can visit the default site. This way your users can access Matomo Analytics without any issues.

sudo a2ensite matomo.conf enables or creates an apache site configuration file which should be enabled to use Matomo. This is the configuration file where the details of your Matomo Analytics site is written.

sudo a2dissite 000-default.conf && sudo a2ensite matomo.conf

Run the following command to enable the Apache rewrite. The sudo a2enmod rewrite command is basically enabling the apache module ‘rewrite’. which is required for Matomo Analytics.

sudo a2enmod rewrite

Finally, restart your apache server with the following command to apply the changes.

sudo systemctl restart apache2

Installing Matomo

Now that you have your LAMP stack setup, it’s time to install Matomo Analytics.

Run the following wget command to download the latest stable version of Matomo to your current directory.


Download matomo

Run the following command to create a new matomo installation directory in the web root directory, unzip the downloaded file, and move the extracted files in the matomo installation directory.

sudo mkdir -p /var/www/matomo && sudo unzip && sudo mv matomo/* /var/www/matomo

Finally, run the following command to set the proper permissions for your matomo instalation directory.

sudo chown -R www-data:www-data /var/www/matomo && sudo chmod -R 755 /var/www/matomo

Accessing Matomo Web UI

Now that you have your LAMP stack and Matomo installed, you’re ready to access the Web UI of Matomo Analytics.

Open your favorite browser and navigate to In the Matomo installation directory, there are sample tools you can use to verify that your installation is fully operational. Click on Next and follow the on-screen instructions to complete your installation.

Matomo web UI


In this tutorial, we have explained the installation of Matomo Analytics and the LAMP stack for Matomo Analytics. We hope that after going through this article, you are able to set up your own Matomo Analytics on your web server.