Matomo/Installation

Installation de Matomo sur une VM Ubuntu

Objectif

Cette procédure décrit l'installation de Matomo sur les VM AJLSM hébergeant les applications Pleade et Drupal.

Elle est destinée à être réutilisée pour les nouveaux projets, indépendamment du client et du nom de domaine.

La configuration Apache, l'intégration Drupal et la publication sécurisée par HAProxy sont détaillées dans des chapitres distincts :

• Matomo/Apache
• Matomo/Drupal
• Matomo/HAProxy
• Matomo/Maintenance

1. Environnement technique

Matomo fonctionne avec Apache 2.4, PHP et MariaDB/MySQL.

Deux modes d'exécution de PHP sont possibles :

• mod_php : PHP est exécuté directement par Apache.
• PHP-FPM : PHP est exécuté par un service indépendant auquel Apache transmet les requêtes PHP.

Le choix dépend de la configuration de la VM. Il n'est pas nécessaire d'installer PHP-FPM lorsque Matomo fonctionne déjà avec mod_php.

Versions PHP

Ubuntu	Version PHP de référence	Observations
Ubuntu 18.04	PHP 8.1	Installation historique avec version PHP ajoutée séparément
Ubuntu 24.04	PHP 8.3	Version fournie par Ubuntu
Ubuntu 26.04	PHP 8.4	Version utilisée sur AD64 en octobre 2026

Vérifier systématiquement la compatibilité entre PHP et la version de Matomo installée.

Composants nécessaires

• Apache 2.4
• PHP avec mod_php ou PHP-FPM
• MariaDB ou MySQL
• Extensions PHP requises par Matomo
• Accès HTTPS, directement ou via HAProxy
• Accès réseau permettant le téléchargement et les mises à jour de Matomo

2. Installation des dépendances PHP

Adapter la version de PHP à celle installée sur la VM.

Ubuntu 24.04 — PHP 8.3

sudo apt install \
  php8.3-mysql php8.3-gd php8.3-curl php8.3-xml \
  php8.3-mbstring php8.3-zip php8.3-intl

Ubuntu 26.04 — PHP 8.4

sudo apt install \
  php8.4-mysql php8.4-gd php8.4-curl php8.4-xml \
  php8.4-mbstring php8.4-zip php8.4-intl

Vérification

php -v
php -m | grep -Ei 'mysqli|pdo_mysql|gd|curl|mbstring|xml|zip|intl'

3. Configuration PHP avec Apache

Identifier le mode PHP utilisé

apache2ctl -M 2>/dev/null | grep -E 'php_module|proxy_fcgi_module|mpm_'

systemctl list-units --all 'php*-fpm.service' --no-pager

php -v

Attention : la présence du module proxy_fcgi_module ne signifie pas nécessairement que PHP-FPM est utilisé. Il faut également vérifier les VirtualHosts et les gestionnaires PHP configurés.

Cas 1 : Apache avec mod_php

Dans cette configuration, PHP est exécuté directement par Apache.

Exemple observé sur AD64 :

mpm_prefork_module (shared)
php_module (shared)

Aucun service PHP-FPM n'est nécessaire.

Vérifier qu'Apache fonctionne :

systemctl is-active apache2

Pour une nouvelle installation utilisant ce mode, installer le module Apache correspondant à la version PHP disponible, par exemple :

sudo apt install libapache2-mod-php

Ne pas modifier le mode d'exécution PHP d'une VM existante sans vérifier les autres applications hébergées.

Cas 2 : Apache avec PHP-FPM

PHP-FPM est une autre architecture possible, notamment lorsqu'une VM utilise plusieurs pools PHP.

Exemple avec PHP 8.4 :

sudo apt install php8.4-fpm

sudo a2enmod proxy_fcgi setenvif
sudo a2enconf php8.4-fpm

sudo apache2ctl configtest
sudo systemctl reload apache2

Vérifier ensuite :

systemctl is-active php8.4-fpm

Important : si plusieurs applications utilisent différentes versions de PHP, privilégier une configuration explicite par VirtualHost ou par pool plutôt que l'activation systématique d'une configuration globale.

Retour d'expérience AD64 — octobre 2026

L'installation Matomo 5.10.1 sur AD64 utilise :

Apache 2.4

PHP 8.4

mod_php

mpm_prefork

MariaDB

Aucun service PHP-FPM n'est actif.

Cette configuration est fonctionnelle et ne nécessite aucune modification.

4. Préparation de MariaDB

Vérifier que MariaDB est installé et actif :

systemctl status mariadb

Matomo nécessite :

• Une base de données dédiée
• Un utilisateur SQL dédié
• Des droits limités à cette base

Exemple générique à adapter :

CREATE DATABASE matomo
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'matomo'@'localhost'
  IDENTIFIED BY 'MOT_DE_PASSE_FORT_A_REMPLACER';

GRANT ALL PRIVILEGES ON matomo.*
  TO 'matomo'@'localhost';

Ne jamais conserver le mot de passe d'exemple dans une installation réelle.

5. Permissions et sécurisation des fichiers Matomo

Principes

L'installation Matomo est située dans :

/var/www/matomo

Sur les VM AJLSM, lorsque PHP-FPM s'exécute sous l'utilisateur `www-data`, les fichiers de Matomo appartiennent normalement à `www-data:www-data`.

Les permissions de référence sont :

Élément	Permissions	Observations
Répertoires de l'application	755	Lecture et traversée autorisées ; écriture réservée au propriétaire
Fichiers de l'application	644	Lecture autorisée ; écriture réservée au propriétaire
config/config.ini.php	600	Fichier sensible contenant notamment les paramètres de connexion à MariaDB
Répertoires temporaires et de configuration	755	Accessibles en écriture au compte PHP-FPM lorsqu'il en est propriétaire
.well-known/acme-challenge	755	Peut appartenir à root:root ; ne pas modifier sans vérifier la configuration ACME

Important : les permissions 755 et 644 ne rendent pas les fichiers accessibles en écriture à tous. Elles permettent uniquement au propriétaire de les modifier.

Configuration initiale

Pour une nouvelle installation dont l'ensemble des fichiers applicatifs doit appartenir à `www-data` :

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

sudo find /var/www/matomo -type d -exec chmod 755 {} \;
sudo find /var/www/matomo -type f -exec chmod 644 {} \;

sudo chmod 600 /var/www/matomo/config/config.ini.php

Attention : ces commandes concernent une installation initiale, avant la création éventuelle de répertoires spécifiques par d'autres services. Ne pas les réexécuter aveuglément sur une installation existante.

Vérifier préalablement le compte utilisé par PHP-FPM. Si celui-ci est différent de `www-data`, adapter les propriétaires et permissions.

Vérification des permissions

stat -c '%A %a %U:%G %n' \
  /var/www/matomo \
  /var/www/matomo/config \
  /var/www/matomo/config/config.ini.php \
  /var/www/matomo/tmp \
  /var/www/matomo/plugins \
  /var/www/matomo/matomo.php

Vérifier la répartition des propriétaires :

sudo find /var/www/matomo -xdev -printf '%u:%g\n' \
  | sort | uniq -c | sort -nr

Identifier les fichiers ou répertoires accessibles en écriture à tous :

sudo find /var/www/matomo -xdev -perm -0002 \
  -printf '%m %u:%g %p\n'

Cette dernière commande ne doit normalement rien retourner.

Vérification des répertoires accessibles en écriture

for DIR in config tmp plugins; do
  if sudo -u www-data test -w "/var/www/matomo/$DIR"; then
    echo "$DIR : écriture OK"
  else
    echo "$DIR : écriture NON autorisée"
  fi
done

Adapter `www-data` si Matomo utilise un autre compte PHP-FPM.

Cas particulier des répertoires ACME

Certains répertoires peuvent être créés et administrés par le mécanisme de validation des certificats Let's Encrypt :

/var/www/matomo/.well-known
/var/www/matomo/.well-known/acme-challenge

Ils peuvent légitimement appartenir à `root:root` avec des permissions `755`.

Ne pas modifier systématiquement leur propriétaire : vérifier au préalable le mécanisme de validation ACME utilisé sur la VM.

Vérification après modification

Après toute modification des permissions :

• Vérifier que l'interface Matomo reste accessible.
• Vérifier que la connexion à MariaDB fonctionne.
• Vérifier qu'aucune erreur de permission n'apparaît dans les journaux Apache/PHP-FPM.
• Vérifier que les statistiques continuent à être collectées.

Retour d'expérience — AD64, octobre 2026

L'audit de `/var/www/matomo` sur AD64 a donné les résultats suivants :

• 13 315 éléments appartenant à `www-data:www-data`.
• 2 répertoires appartenant à `root:root` : `.well-known` et `.well-known/acme-challenge`.
• Répertoires `config`, `tmp` et `plugins` accessibles en écriture à `www-data`.
• Aucun fichier ou répertoire accessible en écriture à tous.
• Fichier `config/config.ini.php` initialement en `644` : passage recommandé en `600`.
• Interface Matomo vérifiée fonctionnelle.

Aucune autre modification des propriétaires ou des permissions n'était nécessaire.

Conclusion : pour les nouvelles installations, appliquer des permissions adaptées dès le départ et réserver l'accès aux fichiers sensibles. Sur les installations existantes, effectuer un audit avant toute modification globale.

6. Configuration Apache et HTTPS

La configuration du VirtualHost Matomo est décrite dans :

Matomo/Apache

Deux architectures sont possibles :

• Apache assure directement la terminaison HTTPS.
• HAProxy assure la terminaison HTTPS et transmet les requêtes à Apache.

Dans l'infrastructure AJLSM utilisant HAProxy, le certificat public est généralement géré sur les répartiteurs de charge.

La procédure de configuration des certificats et des ACL est décrite dans :

Matomo/HAProxy

Pour une installation utilisant directement Certbot sur Apache :

sudo apt install certbot python3-certbot-apache
sudo certbot --apache

Cette procédure Certbot ne doit pas être appliquée automatiquement à une VM dont le HTTPS public est déjà géré par HAProxy.

7. Initialisation de Matomo

Après configuration du VirtualHost, ouvrir dans un navigateur l'URL HTTPS prévue pour Matomo.

L'assistant d'installation permet notamment de :

1. Vérifier les prérequis système
2. Configurer la connexion à MariaDB
3. Initialiser les tables Matomo
4. Créer le compte administrateur
5. Déclarer le premier site suivi

Important : chaque application suivie doit disposer de son propre identifiant de site Matomo lorsque l'on souhaite séparer ses statistiques.

Exemple : une application Internet et une salle de lecture Drupal peuvent être déclarées comme deux sites distincts.

8. Vérifications après installation

Vérifier la version installée

cd /var/www/matomo
sudo -u www-data php console core:version

Vérifier les services

systemctl is-active apache2
systemctl is-active mariadb
systemctl is-active php8.4-fpm

Adapter la version PHP-FPM si nécessaire.

Vérifier les points d'accès

MATOMO_URL="https://matomo.exemple.fr"

curl -I "$MATOMO_URL/matomo.js"
curl -I "$MATOMO_URL/matomo.php"

Note : selon le comportement du serveur, une requête HEAD peut ne pas produire le même résultat qu'une requête GET. Pour vérifier précisément les codes HTTP :

curl -sS -o /dev/null -w "HTTP %{http_code}\n" \
  "$MATOMO_URL/matomo.js"

L'installation de Matomo ne garantit pas à elle seule que les applications transmettent leurs visites. Cette vérification relève des chapitres d'intégration.

9. Intégration aux applications

Drupal

Voir Matomo/Drupal pour :

• L'installation du module Drupal Matomo
• La configuration de l'identifiant du site
• L'adresse HTTPS du serveur Matomo
• Les exclusions des pages d'administration
• Les vérifications de collecte

Pleade

Voir Matomo/Pleade.

Suivi IIIF et événements

• Matomo/IIIF
• Matomo/Evenements

10. Sécurité et maintenance

Après installation, vérifier :

• Que l'interface d'administration Matomo n'est accessible qu'aux utilisateurs ou réseaux autorisés
• Que les points de collecte nécessaires restent accessibles aux visiteurs
• Que le certificat HTTPS est valide
• Que les sauvegardes couvrent la base MariaDB et la configuration Matomo
• Que les mises à jour de sécurité sont suivies

Voir :

• Matomo/HAProxy
• Matomo/Maintenance
• Matomo/Debug

11. Installations de référence

Projet	Serveur	Domaine Matomo	Particularités
AD64	ad64	ad64-matomo.pleade.com	Matomo 5.10.1 ; deux Drupal suivis séparément
APBP2	À compléter	apbp2-matomo.pleade.com	Publication via HAProxy avec restriction de l'administration
MERCURE3	À compléter	mercure3-matomo.pleade.com	Accès restreint à AJLSM

Les paramètres propres à chaque client (domaines, adresses IP, identifiants Matomo, backends HAProxy) ne doivent pas être intégrés directement dans les commandes génériques.