nixpkgs/nixos/modules/services/web-apps/piwik-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-piwik">

  <title>Piwik</title>
  <para>
    Piwik is a real-time web analytics application.
    This module configures php-fpm as backend for piwik, optionally configuring an nginx vhost as well.
  </para>

  <para>
    An automatic setup is not suported by piwik, so you need to configure piwik itself in the browser-based piwik setup.
  </para>


  <section>
    <title>Database Setup</title>

    <para>
      You also need to configure a MariaDB or MySQL database and -user for piwik 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 piwik;
        CREATE USER 'piwik'@'localhost' IDENTIFIED WITH unix_socket;
        GRANT ALL PRIVILEGES ON piwik.* TO 'piwik'@'localhost';

        # For MySQL
        INSTALL PLUGIN auth_socket SONAME 'auth_socket.so';
        CREATE DATABASE piwik;
        CREATE USER 'piwik'@'localhost' IDENTIFIED WITH auth_socket;
        GRANT ALL PRIVILEGES ON piwik.* TO 'piwik'@'localhost';
      </programlisting>

      Then fill in <literal>piwik</literal> as database user and database name, and leave the password field blank.
      This authentication works by allowing only the <literal>piwik</literal> unix user to authenticate as the 
      <literal>piwik</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>
    <title>Backup</title>
    <para>
      You only need to take backups of your MySQL database and the
      <filename>/var/lib/piwik/config/config.ini.php</filename> file.
      Use a user in the <literal>piwik</literal> group or root to access the file.
      For more information, see <link xlink:href="https://piwik.org/faq/how-to-install/faq_138/" />.
    </para>
  </section>


  <section>
    <title>Issues</title>
    <itemizedlist>
      <listitem>
        <para>
          Piwik'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>
          Piwik 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>

      <listitem>
        <para>
          Sending mail from piwik, e.g. for the password reset function, might not work out of the box:
          There's a problem with using <command>sendmail</command> from <literal>php-fpm</literal> that is
          being investigated at <link xlink:href="https://github.com/NixOS/nixpkgs/issues/26611" />.
          If you have (or don't have) this problem as well, please report it. You can enable SMTP as method
          to send mail in piwik's <quote>General Settings</quote> > <quote>Mail Server Settings</quote> instead.
        </para>
      </listitem>
    </itemizedlist>
  </section>


  <section>
    <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-piwik.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>