Webarchitects Matomo Ansible Role

This repository contains an Ansible role for installing and upgrading Matomo servers using the command line and web based installer.

See the defaults for the default options, please use a release tag in your requirements.yml file if you use this role.

Note that this role don't add the matomo_user user account or the matomo_group group or create the matomo_html, matomo_private or matomo_logs directories, as we use the Webarchitects users role for this.

Install Matomo

By default only these tasks are run:

main.yml
  |
  \-- check_variables.yml
  |     |
  |     \-- check_version.yml
  |     |
  |     \-- check_auth.yml
  |     |
  |     \-- check_latest_version.yml
  |
  \-- upgrade.yml
  |
  \-- install.yml
  |    |
  |    \-- download.yml
  |    |
  |    \-- install_web.yml
  |
  \-- geolocation.yml
  |
  \-- settings.yml
  |
  \-- cron.yml

Upgrading Matomo

This role works fine for upgrading Matomo sites, for Matomo 4.6.1 and upwards it also includes scripts for deleting files.

Matomo user accounts

If a superuser username, password and token authentication string are provided (these can be sorted encrypted using Ansible vault on the Ansible controller) then this role can also be used to add Matomo user accounts and sites using the Matomo API.

To add a Matomo user account include this role with tasks from user_present.yml and then the tasks in these files will be run:

user_present.yml
  |
  \-- check_login.yml
  |     |
  |     \-- update_email.yml
  |     |
  |     |-- add_user.yml
  |
  \-- check_password.yml
        |
        \-- update_password.yml

Since a users password is needed to generate a token_auth which is in turn needed to automatically configure the Matomo WordPress plugin this role will optionally store a record of passwords (but doesn't prevent using from changing them) and reset them when needs be in a YAML file format based on the results of the UsersManager.getUsersPlusRole API method:

---
matomo_accounts:
  - login: user
    email: [email protected]
    password: XXX
    superuser_access: false
    role: noaccess
    capabilities: []

Matomo sites

To add a Matomo site include this role with tasks from site_present.yml and then the tasks in these files will be run:

site_present.yml
  |
  \-- get_all_sites.yml
  |
  \-- get_sites_id_from_site_url.yml
  |     |
  |     \-- check_main_url.yml
  |
  \-- update_site.yml
  |
  \-- add_site.yml

Duplicate sites

To check (in a rather slow manner) for two sites having the same URL include this role with tasks from check_sites.yml and then the tasks in these files wil be run:

check_site.yml
  |
  \-- check_duplicate_urls.yml
        |
        \-- check_duplicate_url.yml

Debugging

Using curl for testing / development:

export TOKEN_AUTH=foo
curl -d "module=API&token_auth=${TOKEN_AUTH}&method=SitesManager.getAllSites&format=JSON" https://matomo.example.org/

Ansible Galaxy and repo URL

The primary URL of this repo is https://git.coop/webarch/matomo however it is also mirrored to GitHub and available via Ansible Galaxy.

If you use this role please use a tagged release, see the release notes.

This role can also be used with the localhost repo to install matomo locally.

Copyright

Copyright 2018-2024 Chris Croome, <[email protected]>.

This role is released under the same terms as Ansible itself, the GNU GPLv3.