diff options
author | pennae <github@quasiparticle.net> | 2023-01-03 07:41:04 +0100 |
---|---|---|
committer | pennae <github@quasiparticle.net> | 2023-01-10 10:31:58 +0100 |
commit | 66fdc39d804eb585f4bf94993bf4abeb5469f1ed (patch) | |
tree | c5dac0b5df819c3cffd185f3d6788d533ec2105f | |
parent | 760eaa3c940d808f7b268a49e27651ec3a2b1ffe (diff) |
nixos/matomo: convert manual chapter to MD
-rw-r--r-- | nixos/modules/services/web-apps/matomo-doc.md | 77 | ||||
-rw-r--r-- | nixos/modules/services/web-apps/matomo-doc.xml | 180 | ||||
-rw-r--r-- | nixos/modules/services/web-apps/matomo.nix | 2 |
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 0000000000000..f5536a35f7a89 --- /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 78cd6dd4d4349..af445a9e627e1 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.<name>.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 > 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/" 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.<name>.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 0435d21ce8a2b..fcc5dc5650e30 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 ]; }; |