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 000000000000..f5536a35f7a8 --- /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 +. + +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 +. + +## 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..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 78cd6dd4d434..af445a9e627e 100644 --- a/nixos/modules/services/web-apps/matomo-doc.xml +++ b/nixos/modules/services/web-apps/matomo-doc.xml @@ -1,26 +1,23 @@ - - 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 - + + Matomo - 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: - + 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 + + 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; @@ -33,75 +30,76 @@ 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 - . - - - - Of course, you can use password based authentication as well, e.g. when the - database is not on the same host. - -
-
- 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 at - Administration > System > General Settings. - - - - With automatic archive processing, you can now also enable to - - delete old visitor 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 - - - You only need to take backups of your MySQL database and the - /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 - . - -
-
- 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. + 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/. - - -
-
- Using other Web Servers than nginx - - - You can use other web servers by forwarding calls for - index.php and piwik.php to the - 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. - -
+ + Of course, you can use password based authentication as well, e.g. + when the database is not on the same host. + +
+
+ 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 at + Administration > System > General Settings. + + + With automatic archive processing, you can now also enable to + delete + old visitor 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 + + You only need to take backups of your MySQL database and the + /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 + + + + 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 + + You can use other web servers by forwarding calls for + index.php and piwik.php + to the + 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.nix b/nixos/modules/services/web-apps/matomo.nix index 0435d21ce8a2..fcc5dc5650e3 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 ]; };