diff --git a/Dockerfile b/Dockerfile index 67e9eae..d00272b 100644 --- a/Dockerfile +++ b/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 diff --git a/docs/HowTos/HOWTO-premium-plugins.md b/docs/HowTos/HOWTO-premium-plugins.md new file mode 100644 index 0000000..f65d08f --- /dev/null +++ b/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 "" +``` + +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 [...] +``` + +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. diff --git a/files/config.ini.php b/files/config.ini.php index 11ca2d7..412e5f6 100644 --- a/files/config.ini.php +++ b/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"