Merge pull request #22 from MITLibraries/INFRA-517

INFRA-517 Part 1: Update Matomo Version

Author: cabutlermit

Dockerfile

@@ -1,4 +1,6 @@
-FROM matomo:5.2.2
+FROM matomo:5.3.1
+  # checkov:skip=CKV_DOCKER_2:Skipping HEALTHCHECK configuration for now
+  # checkov:skip=CKV_DOCKER_3:Intentionally using root for the user
 
 # Add the EnvironmentVariables plugin
 COPY ./files/plugin-EnvironmentVariables-5.0.3/ /var/www/html/plugins/EnvironmentVariables
@@ -14,7 +16,6 @@ COPY --chmod=0644 --chown=root:root ./files/lang-htaccess /var/www/html/lang/.ht
 COPY --chmod=0644 --chown=root:root ./files/config-htaccess /var/www/html/config/.htaccess
 COPY --chmod=0644 --chown=root:root ./files/tmp-htaccess /var/www/html/tmp/.htaccess
 
-
 # Create mount point for EFS partition
 RUN mkdir -p /mnt/efs
 

docs/HowTos/HOWTO-premium-plugins.md

@@ -0,0 +1,60 @@
+# Premium Plugins
+
+Premium plugins are those that require a license key. In our docker-ized implementation of Matomo, this gets tricky.
+
+After some initial testing in Dev1, it's not as simple as just dumping the new plugin into the container and redeploying because of the following reasons.
+
+1. The license key is stored in the database, **NOT** in the `config.ini.php` file.
+1. Some plugins require changes to the database tables or just new tables. This requires that the plugin installation process is triggered to kick off the script that updates the tables.
+1. The *Marketplace* plugin must be active for license keys to work.
+
+## The config.ini.php file
+
+The `config.ini.php` file has two lists of plugins under two different headings.
+
+* One heading, `[PluginsInstalled]` is the list of plugins that are installed (but might be active or inactive) on the server. This should be a 1-1 match for the folders in the `/var/www/html/plugins` folder in the container.
+* The other heading, `[Plugins]` is the list of **active** plugins. 
+* Each plugin might have its own section in the `config.ini.php` file with plugin-specific settings.
+
+In the end, the premium plugin installation is a two-pass process.
+
+## Process
+
+### High level overview
+
+1. Install license key (via UI or CLI) so that it is in the database.
+2. Go through a dev -> stage -> prod deployment cycle of the container to install the plugin folder(s) into the container and update the `config.ini.php` file with new line(s) in the `[PluginsInstalled]` section.
+3. Activate the new plugin(s) (via UI or CLI) so that any database changes are properly executed.
+4. Go through a dev -> stage -> prod deployment cycle of the container to match the updated `config.ini.php` file on the server.
+
+### Details for each step
+
+#### 1. Install the license key
+
+Before installing the license key, the *Marketplace* plugin must be activated. This is a one-time update to the `config.ini.php` file to add the *Marketplace* pluging to the `[Plugins]` section.
+
+According to the support team at Matomo, the premium license key can be installed in two instances of Matomo, "stage" and "prod." So, we can do some initial validation of a license key in Dev1, but the key cannot remain installed in the Dev1 instance. The license key installation can either be done by a user with "superuser" privileges in the Matomo web UI or it can be done by a member of InfraEng who has ssh access to the running container task/service. The CLI command is
+
+```bash
+./console marketplace:set-license-key --license-key=LICENSE-KEY "<key>"
+```
+
+This needs to be done on each of the stage & prod instances of Matomo.
+
+#### 2. Install plugin
+
+In this phase, the files are installed in the container and the `config.ini.php` is updated to match the installation. This will **not** activate the plugins, it will just make them visible in the UI. The only new lines in the `config.ini.php` should be in the `[PluginsInstalled]` section.
+
+#### 3. Activate plugin
+
+Once the plugin is installed, it's time to activate it. In the UI, it's just a matter of clicking the `Activate` link for the plugin. For the CLI, the command is
+
+```bash
+./console plugin:activate [<plugin>...]
+```
+
+This will change the `config.ini.php` file on the container. It is **very** important to capture these changes and put them back in the `config.ini.php` in the container (see step 4).
+
+#### 4. Deploy new config.ini.php
+
+After capturing the changes to `config.ini.php`, go through another round of dev -> stage -> prod deploys.

files/config.ini.php

@@ -32,6 +32,7 @@
 ; maximum number of rows for sub-tables of the Events tables (eg. for the subtables Categories>Actions or Categories>Names).
 datatable_archiving_maximum_rows_subtable_events = 100
 
+
 [mail]
 
 [Plugins]
@@ -87,6 +88,7 @@
 Plugins[] = "Resolution"
 Plugins[] = "DevicePlugins"
 Plugins[] = "Heartbeat"
+Plugins[] = "Marketplace"
 Plugins[] = "Intl"
 Plugins[] = "Tour"
 Plugins[] = "PagePerformance"