nixos/matomo: convert manual chapter to MD
This commit is contained in:
pennae
@@ -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.
|
||||
@@ -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>
|
||||
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>
|
||||
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:
|
||||
</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>
|
||||
|
||||
@@ -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 ];
|
||||
};
|
||||
|
||||
Reference in New Issue
Block a user