nixos/matomo: convert manual chapter to MD

3 files changed, 168 insertions, 91 deletions

diff --git a/nixos/modules/services/web-apps/matomo-doc.md b/nixos/modules/services/web-apps/matomo-doc.md
new file mode 100644
index 00000000000..f5536a35f7a
--- /dev/null
+++ b/nixos/modules/services/web-apps/matomo-doc.md
@@ -0,0 +1,77 @@
+# Matomo {#module-services-matomo}
+
+Matomo is a real-time web analytics application. This module configures
+php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.
+
+An automatic setup is not suported by Matomo, so you need to configure Matomo
+itself in the browser-based Matomo setup.
+
+## Database Setup {#module-services-matomo-database-setup}
+
+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:
+```
+# 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';
+```
+Then fill in `matomo` as database user and database name,
+and leave the password field blank. This authentication works by allowing
+only the `matomo` unix user to authenticate as the
+`matomo` database user (without needing a password), but no
+other users. For more information on passwordless login, see
+<https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/>.
+
+Of course, you can use password based authentication as well, e.g. when the
+database is not on the same host.
+
+## Archive Processing {#module-services-matomo-archive-processing}
+
+This module comes with the systemd service
+`matomo-archive-processing.service` and a timer that
+automatically triggers archive processing every hour. This means that you
+can safely
+[disable browser triggers for Matomo archiving](
+https://matomo.org/docs/setup-auto-archiving/#disable-browser-triggers-for-matomo-archiving-and-limit-matomo-reports-to-updating-every-hour
+) at
+`Administration > System > General Settings`.
+
+With automatic archive processing, you can now also enable to
+[delete old visitor logs](https://matomo.org/docs/privacy/#step-2-delete-old-visitors-logs)
+at `Administration > System > Privacy`, but make sure that you run `systemctl start
+matomo-archive-processing.service` at least once without errors if
+you have already collected data before, so that the reports get archived
+before the source data gets deleted.
+
+## Backup {#module-services-matomo-backups}
+
+You only need to take backups of your MySQL database and the
+{file}`/var/lib/matomo/config/config.ini.php` file. Use a user
+in the `matomo` group or root to access the file. For more
+information, see
+<https://matomo.org/faq/how-to-install/faq_138/>.
+
+## Issues {#module-services-matomo-issues}
+
+  - 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.
+
+## Using other Web Servers than nginx {#module-services-matomo-other-web-servers}
+
+You can use other web servers by forwarding calls for
+{file}`index.php` and {file}`piwik.php` to the
+[`services.phpfpm.pools.<name>.socket`](#opt-services.phpfpm.pools._name_.socket)
+fastcgi unix socket. You can use
+the nginx configuration in the module code as a reference to what else
+should be configured.
diff --git a/nixos/modules/services/web-apps/matomo-doc.xml b/nixos/modules/services/web-apps/matomo-doc.xml
index 78cd6dd4d43..af445a9e627 100644
--- a/nixos/modules/services/web-apps/matomo-doc.xml
+++ b/nixos/modules/services/web-apps/matomo-doc.xml
@@ -1,26 +1,23 @@
-<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>
-
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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>
-   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>
+    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:
+    </para>
+    <programlisting>
 # For MariaDB
 INSTALL PLUGIN unix_socket SONAME 'auth_socket';
 CREATE DATABASE matomo;
@@ -33,75 +30,76 @@ 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 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.
+      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/" role="uri">https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/</link>.
     </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
-   <link linkend="opt-services.phpfpm.pools._name_.socket"><literal>services.phpfpm.pools.&lt;name&gt;.socket</literal></link> fastcgi unix socket. You can use
-   the nginx configuration in the module code as a reference to what else
-   should be configured.
-  </para>
- </section>
+    <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 &gt; System &gt; 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 &gt; System &gt; 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/" role="uri">https://matomo.org/faq/how-to-install/faq_138/</link>.
+    </para>
+  </section>
+  <section xml:id="module-services-matomo-issues">
+    <title>Issues</title>
+    <itemizedlist spacing="compact">
+      <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
+      <link linkend="opt-services.phpfpm.pools._name_.socket"><literal>services.phpfpm.pools.&lt;name&gt;.socket</literal></link>
+      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>
diff --git a/nixos/modules/services/web-apps/matomo.nix b/nixos/modules/services/web-apps/matomo.nix
index 0435d21ce8a..fcc5dc5650e 100644
--- a/nixos/modules/services/web-apps/matomo.nix
+++ b/nixos/modules/services/web-apps/matomo.nix
@@ -325,6 +325,8 @@ in {
   };
 
   meta = {
+    # Don't edit the docbook xml directly, edit the md and generate it:
+    # `pandoc matomo-doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > matomo-doc.xml`
     doc = ./matomo-doc.xml;
     maintainers = with lib.maintainers; [ florianjacob ];
   };