nixpkgs/nixos/modules/services/web-apps/matomo-doc.xml

<chapter xmlns="http://docbook.org/ns/docbook"
         xmlns:xlink="http://www.w3.org/1999/xlink"
         xmlns:xi="http://www.w3.org/2001/XInclude"
         version="5.0"
         xml:id="module-services-matomo">
 <title>Matomo</title>
 <para>
  Matomo is a real-time web analytics application. This module configures
  php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.
 </para>
 <para>
  An automatic setup is not suported by Matomo, so you need to configure Matomo
  itself in the browser-based Matomo setup.
 </para>

 <section xml:id="module-services-matomo-database-setup">
  <title>Database Setup</title>
  <para>
   You also need to configure a MariaDB or MySQL database and -user for Matomo
   yourself, and enter those credentials in your browser. You can use
   passwordless database authentication via the UNIX_SOCKET authentication
   plugin with the following SQL commands:
   <programlisting>
        # For MariaDB
        INSTALL PLUGIN unix_socket SONAME 'auth_socket';
        CREATE DATABASE matomo;
        CREATE USER 'matomo'@'localhost' IDENTIFIED WITH unix_socket;
        GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';

        # For MySQL
        INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';
        CREATE DATABASE matomo;
        CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket;
        GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
   </programlisting>
   Then fill in <literal>matomo</literal> as database user and database name,
   and leave the password field blank. This authentication works by allowing
   only the <literal>matomo</literal> unix user to authenticate as the
   <literal>matomo</literal> database user (without needing a password), but no
   other users. For more information on passwordless login, see
   <link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />.
  </para>

  <para>
   Of course, you can use password based authentication as well, e.g. when the
   database is not on the same host.
  </para>
 </section>

 <section xml:id="module-services-matomo-archive-processing">
  <title>Archive Processing</title>
  <para>
   This module comes with the systemd service <literal>matomo-archive-processing.service</literal>
   and a timer that automatically triggers archive processing every hour.
   This means that you can safely
   <link xlink:href="https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour">
    disable browser triggers for Matomo archiving
   </link> at <literal>Administration > System > General Settings</literal>.
  </para>
  <para>
   With automatic archive processing, you can now also enable to
   <link xlink:href="https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs">
    delete old visitor logs
   </link> at <literal>Administration > System > Privacy</literal>,
   but make sure that you run <literal>systemctl start matomo-archive-processing.service</literal>
   at least once without errors if you have already collected data before,
   so that the reports get archived before the source data gets deleted.
  </para>
 </section>

 <section xml:id="module-services-matomo-backups">
  <title>Backup</title>
  <para>
   You only need to take backups of your MySQL database and the
   <filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user
   in the <literal>matomo</literal> group or root to access the file. For more
   information, see
   <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.
  </para>
 </section>

 <section xml:id="module-services-matomo-issues">
  <title>Issues</title>
  <itemizedlist>
   <listitem>
    <para>
     Matomo's file integrity check will warn you. This is due to the patches
     necessary for NixOS, you can safely ignore this.
    </para>
   </listitem>
   <listitem>
    <para>
     Matomo will warn you that the JavaScript tracker is not writable. This is
     because it's located in the read-only nix store. You can safely ignore
     this, unless you need a plugin that needs JavaScript tracker access.
    </para>
   </listitem>
  </itemizedlist>
 </section>

 <section xml:id="module-services-matomo-other-web-servers">
  <title>Using other Web Servers than nginx</title>

  <para>
   You can use other web servers by forwarding calls for
   <filename>index.php</filename> and <filename>piwik.php</filename> to the
   <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use
   the nginx configuration in the module code as a reference to what else
   should be configured.
  </para>
 </section>
</chapter>