Managed instance of Matomo, a real-time Web analytics application.


The matomo role sets up the Matomo PHP application and Nginx as reverse proxy with an automatically managed Letsencrypt certificate.


Matomo requires manual setup: you need to set the host name, create a database and run the Web installer.

Matomo requires a MySQL-compatible database which is not activated automatically. You can put the database on the same machine or use a separate one. We recommend the percona80 role for the database.

Add Matomo NixOS config

Before activating the matomo role, add at least the following custom config:

# /etc/local/nixos/matomo.nix
{ config, lib, ... }:
  flyingcircus.roles.matomo = {
    hostname = "";

See Custom NixOS-native configuration for general information about writing custom NixOS modules in /etc/local/nixos.

Create the database

Assuming that percona80 is running on the same machine, create a database with full privileges for the local matomo user. Matomo will create the necessary database objects during the Web installer process.

sudo -u mysql mysql
create user matomo@localhost;
create database matomo;
grant all on matomo.* to matomo@localhost;

Run the Web installer

Go to the configured URL, for example and start the Web installer.

On the third step which sets up the database, use localhost as “Database Server” and matomo for both “Login” and “Database Name”. Keep “Password” empty and remove the default “Table Prefix”. “Adapter” should be PDO\MySQL.

After clicking “Next”, Matomo confirms that tables have been created.

Finish the following steps and log in with your admin credentials.


You probably want geolocation which requires an external database. Set it up it via Administration -> System -> Geolocation. Choose DBIP / GeoIP 2 and Matomo will automatically download the database.

Also see Setting up accurate visitors geolocation in the Matomo FAQ.

Archive Processing

The role automatically sets up the matomo-archive-processing service which runs every hour. You can disable browser-triggered archiving, especially for high-traffic websites:

Go to Administration > System -> General Settings, and select:

Archive reports when viewed from the browser: No



Please do not try to update Matomo manually, files will be overwritten!

Updates are handled by the role. New versions overwrite files in the installation directory, copied from the matomo Nix package.


As sudo-srv user, use matomo-console to run various Matomo management commands:

sudo -u matomo matomo-console



As sudo-srv or service user, put plugin bundles in /var/lib/matomo/plugins. Activate plugins with:

sudo -u matomo matomo-console plugin:activate ExamplePlugin

NixOS Options


Archive processing is enabled by default.


Put additional nginx virtual host settings here which are the same options as services.nginx.virtualHosts.<name>.*, for example:

  services.matomo.nginx = {
    default = true;
    basicAuth = "FCIO login";
    basicAuthFile = "/etc/local/htpasswd_fcio_users";


The role defines the following Sensu checks:

  • matomo-config

  • matomo-permissions

  • matomo-unexpected-files

  • matomo-version