Matomo - Analytics Package

Installation

Assumptions

  • Previously installed and running Local, Production and Staging ISLE Host systems are in place already.

  • You'll need to use the ISLE images tagged as 1.3.0 and higher.


Installation Instructions

Adapted from @DiegoPino's original example ISLE config: https://github.com/Islandora-Collaboration-Group/isle_matomo_docker

Edit 1: Modify Docker-Compose & .env files

  • Create a data/matomo directory to persist your Matomo application. You will probably want to put this in a git repo if you're deploying to multiple servers and don't want to have to re-install plugins/etc for each environment. We recommend using an appropriate .gitignore before checking that in (e.g. https://raw.githubusercontent.com/matomo-org/matomo/4.x-dev/.gitignore)

  • Copy the files in config/matomo into a new directory data/matomo/config to seed your Matomo application's config. You'll want to commit this to your new Git repo. If you are going to use the instructions below to run Matomo through your main domain (via a /matomo proxy URL) you will need to add proxy_uri_header = 1 to your config/config.ini.php file's "General" section.

  • Within your docker-compose.*.yml, add the following blocks to enable new services:

matomo:
  image: matomo:3-fpm
  container_name: isle-matomo-${CONTAINER_SHORT_ID}
  env_file:
    - .env
  networks:
    isle-internal:
  links:
    - mysql
  depends_on:
    - mysql
    - traefik
  volumes:
    - ./data/matomo/html/:/var/www/html
  labels:
    - traefik.enable=false

matomo-nginx:
  image: nginx
  container_name: isle-matomo-nginx-${CONTAINER_SHORT_ID}
  volumes:
    - ./config/matomo-nginx/ngix.conf:/etc/nginx/nginx.conf:ro
    - ./data/matomo/html/:/var/www/html
  links:
    - matomo
  networks:
    - isle-internal
  ports:
    - "9002:9020"
  labels:
    - traefik.enable=true
    - traefik.backend=matomo
    - traefik.frontend.entryPoints=https
    - traefik.port=9020
    - traefik.frontend.passHostHeader=true
    - "traefik.frontend.rule=Host:${BASE_DOMAIN}; PathPrefixStrip: /matomo;"
    - traefik.docker.network==${COMPOSE_PROJECT_NAME}_isle-internal

whoami:
  image: containous/whoami # A container that exposes an API to show its IP address
  container_name: isle-whoami-${CONTAINER_SHORT_ID}
  labels:
    - "traefik.frontend.rule=Host:whoami.${BASE_DOMAIN};"

Your traefik service ports definition needs modifying like this:

    ports:
      - "80:80"
      - target: 443
        published: 443
        protocol: tcp
        mode: host
      - "8080:8080"

Your traefik labels definition needs an extra line before the line selecting port 8080:

      - traefik.frontend.passHostHeader=true

Your apache service needs to have any PathPrefix removed from the frontendrule. It was probably like this:

- "traefik.frontend.rule=Host:${BASE_DOMAIN}; PathPrefix: /, /cantaloupe"

So now this rule should be changed such that apache doesn't intercept /matomo requests through the main domain. This new edit shouldn't interfere with other ISLE operations:

- "traefik.frontend.rule=Host:${BASE_DOMAIN};"

  • Start up the ISLE Docker containers again. docker-compose up -d

Install and Configure Matomo

  1. Create your new Matomo database and call it matomo_db. Drush should be able to do this, e.g. drush sql-create --db-su="root" --db-su-pw="MYQSL_ROOT_PWD" --db-url="mysql://DRUPAL_DB_USER:DRUPAL_DB_PWD@mysql/matomo_db". If you use a different method, ensure that you make a database user and password to access the database rather than using root credentials below.

  2. Add <yourdomain> to your /etc/hosts file and visit that URL. You should see a Matomo install dialog at https://<yourdomain>/matomo. Additional support may be found here: https://matomo.org/docs/installation/

  3. Use the following values for Database Setup:

  4. Database Server: "mysql"

  5. Login: the value of DRUPAL_DB_USER in your local.env file
  6. Password: the value of DRUPAL_DB_PASS in your local.env file
  7. Database Name: "matomo_db"
  8. Table Prefix: "matomo_"
  9. Adapter: PDO\MYSQL

This creates files in a config folder and you'll need to do this for each environment or manually copy (or use Git to sync) those files between environments.

  1. Click "Next" a couple times until you get to the "Super User" creation page. Enter (and save!) credentials for your Matomo login.

  2. The next screen prompts you to "Setup a Website". Enter your website name ("Islandora" is good, if you're planning on following the LASIR instructions for integrating with Islandora), the URL you're using for the environment you're in, and a timezone. Select "Not an Ecommerce site".

  3. The next screen will provide you with a tracking code block. Copy it out for use later, or plan to log into the Matomo dashboard later to fetch it again.

  4. Log in. Allow Matomo to update if it wants to. You may have to do this in order to access the settings areas.

  5. Don't forget to check in all the new files in your Matomo Git repo, if you're tracking it that way.


Configure Islandora to coordinate with Matomo

Now you can pick up from here: https://github.com/Islandora-Collaboration-Group/islandora_matomo#setup-matomo-for-this-module

Important sub-steps:

  1. Create an extra "website" if you need to track Authors/Department data.

  2. Install the "Plugin" for "Custom Dimensions" to enable Islandora integration.

  3. Add the "Custom Dimensions" in the order requested

  4. Fetch your API code to paste into Islandora admin.


Testing


Need Help?

We welcome questions, suggestions, contributions, and respond promptly to requests for technical help. Please join us in the following: