Matomo Analytics is a free software self hosted alternative to Google Analytics. Matomo was once named Piwik or PHPMyVisites.

This howto is tested on:

  • Debian 10.0 Buster

This howto is tested with these versions of the software:

  • 4.0.5


This howto requires:


Set the application’s hosting domain name:


Set the MariaDB (MySQL) server host:


If the MariaDB (MySQL) server is remote, mysql-tools try a networked login to the server or, on failure, a SSH call to the mysql-tools installed on the server host.

Set the method used to setup a HTTPS connnection: “auto” to automatically create a free “Let’s Encrypt (en)” SSL certificate, or the name of a SSL certificate created as described by Create a SSL / TLS certificate on Debian (optional, recommended):



Detect if sudo is available (“command” is used if not):

command type -f 'sudo' &>'/dev/null' && cmdProxy='sudo'

Set the software code (used to set the installation paths):


Set the installation path:


Set the cache path:


Create the installation path:

${cmdProxy} mkdir --parent "${installPath}"

Detect if HTTPS is used:

[[ -n "${sslKeyName}" \
    && ( -e "/etc/ssl/private/${sslKeyName}.key" \
    || "${sslKeyName}" = 'auto' ) ]] && protocol="https"

Environment setup

Install the required software:

${cmdProxy} apt-get install apg unzip php-mysql php-gd php-cli \
    php-geoip sudo

Adjust PHP settings:

${cmdProxy} php-tools --for="${softwareCode}" --set 'memory_limit' '128M'
${cmdProxy} php-tools --for='${softwareCode}' --fix 'always_populate_raw_post_data' '\-1'
${cmdProxy} php-tools --for='${softwareCode}' --set 'xdebug.max_nesting_level' '500'

Reload PHP configuration:

${cmdProxy} php-tools --reload

Application’s installation

Create a temporary location to download and unzip the application sources:

archivePath="$(command mktemp --directory)"
${cmdProxy} ln -s "${installPath}" "${archivePath}/matomo"

Download the software’s latest stable version:

${cmdProxy} biapy-downloader --extract --output-path="${installPath}" \
    --strip-components=1 ''

Allow a Web process to change the configuration:

${cmdProxy} chown -R 'www-data:www-data' "${installPath}/config"

LSB conformity

Setup a folder structure conform with LSB:

${cmdProxy} mkdir --parent "$(command dirname "${cachePath}")"
if [ -d "${installPath}/tmp" ]; then
  ${cmdProxy} mv "${installPath}/tmp" "${cachePath}"
  ${cmdProxy} chown -R 'www-data:www-data' "${cachePath}"
  ${cmdProxy} ln -s "${cachePath}" "${installPath}/tmp"

Database creation

Create the database:

command mysql-tools --server="${mysqlHost}" --with-ssh \
        --auto-hosts --db-prefix="${softwareCode}" --create "${domain}"

Store preciously the login information displayed.

VirtualHost setup

Create the HTTP server configuration for the domain:

if [[ -n "${sslKeyName}" \
  && ( -e "/etc/ssl/private/${sslKeyName}.key" \
  || "${sslKeyName}" = 'auto' ) ]]; then
  ${cmdProxy} a2tools --ssl="${sslKeyName}" \
    "${domain}" "${installPath}"
${cmdProxy} a2tools  \
  "${domain}" "${installPath}"

The software is now available on the domain for HTTP and HTTPS protocols.

Initial setup

Start the initial setup of the software by visiting the URL shown by:

echo "http://${domain}/"

Setup the software to use the database created above.

Warning : In order to limit the impact of SQL injection attack, choose a random table prefix, as obtained with:

echo "Randomized table prefix : $(command apg -q -a 0 -n 1 -M NCL)_"

Choose a secure (and random) password for the administration account:

echo "Admin account password : '$(command apg -q -a 0 -n 1 -M NCL)'"

Advanced setup

Auto-archiving of reports

By default, Matomo compute visits statistics on consultation. For websites with more than a few hundred visits a day, this computation slow down the statistics frontend. This problem is solved by running the computation beforehand with a cron task.

Create a log file for the archiving process:

${cmdProxy} touch "${archivingLog}" "${archivingErrorLog}"
${cmdProxy} chown 'www-data:adm' "${archivingLog}" "${archivingErrorLog}"

Setup log rotation:

${cmdProxy} tee "/etc/logrotate.d/${softwareCode}-archive" \
<<< "# Logrotate configuration file for Matomo archiving

${archivingLogBase}*.log {
    rotate 12
    create 664 www-data adm
    su www-data adm

Setup a cron task to hourly archive the visits reports:

${cmdProxy} tee "/etc/cron.d/${softwareCode}-archiver-${domain//./-}" \
  <<< "#
# Hourly archiving for ${domain}.
# Every hours at 5mn past o'clock.
5 *    * * *    www-data    test -f '${installPath}/console' -a -x '/usr/bin/php' && /usr/bin/php '${installPath}/console' 'core:archive' --url='${protocol}://${domain}' >>'${archivingLog}' |& tee -a '${archivingErrorLog}'"

Reload cron daemon configuration:

${cmdProxy} systemctl 'restart' 'cron'

Make sure the cron task will actually work by running the script as the cron task user:

sudo -u 'www-data' php "${installPath}/console" 'core:archive' \

Disable triggering archiving by browsing the Web frontend:

sudo -v -u 'www-data' && {
  sudo -u 'www-data' php "${installPath}/console" 'config:set' --section='General' --key='time_before_archive_considered_outdated' --value='3600'
  sudo -u 'www-data' php "${installPath}/console" 'config:set' --section='General' --key='enable_browser_archiving_triggering' --value='false'

Force HTTPS for users’ sessions

If possible (HTTPS host configured), force the use of HTTPS for users’ sessions:

sudo -u 'www-data' php "${installPath}/console" 'config:set' \
  --section='General' --key='force_ssl' --value='1'

Reverse proxy support

If a reverse proxy is used to access the software, setup Matomo to get the visitors’ IP addresses from the X_FORWARDED_FOR HTTP header:

sudo -v -u 'www-data' && {
  sudo -u 'www-data' php "${installPath}/console" 'config:set' \
  --section='General' --key='proxy_client_headers[]' --value='HTTP_X_FORWARDED_FOR'
  sudo -u 'www-data' php "${installPath}/console" 'config:set' \
  --section='General' --key='proxy_host_headers[]' --value='HTTP_X_FORWARDED_HOST'

Une alternative possible si l’outil est hébergé sur un serveur Apache 2 est de suivre le guide Obtenir l’adresse IP réelle d’un visiteur accédant à un serveur Apache 2 à travers un reverse proxy.

If the reverse proxy provide HTTPS encryption, set the software to assume its use:

 sudo -u 'www-data' php "${installPath}/console" 'config:set' \
  --section='General' --key='assume_secure_protocol' --value='1'


Setup the regular backup of installed software:

${cmdProxy} bu-tools --add="${installPath}"

Make sure the database is backed-up (see Install MariaDB (MySQL) on Debian).

Automatic updates

Install the updater script :

${cmdProxy} wget --quiet --no-check-certificate \
    --output-document='/usr/local/bin/matomo-updater' \

Declare the downloaded file as executable:

${cmdProxy} chmod +x '/usr/local/bin/matomo-updater'

Configure biapy-updater automatic updates to check for newer versions of the updater script:

${cmdProxy} tee -a '/etc/biapy-updater.conf' <<< 'matomo-updater'

Setup a cron task checking daily for newer versions of the software:

${cmdProxy} tee "/etc/cron.d/${softwareCode}-updater-${domain//./-}" \
  <<< "#
# Regular cron jobs for updating Matomo at ${domain}
# Every night at 5:45.
45 5 * * *   root    PATH=\"\$PATH:/usr/local/bin\"; test -x /usr/local/bin/matomo-updater && /usr/local/bin/matomo-updater '${installPath}'"

Reload cron daemon configuration:

${cmdProxy} systemctl 'restart' 'cron'


Categories: Statistics


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.