Tips and considerations for updating a high traffic Matomo server

We’re going to discuss the procedure to be followed, when you wish to migrate and upgrade your existing Matomo On-premises to the latest version of Matomo On-premises.

So whether you are using the core Matomo Analytics platform (community version) or using an
older version of Matomo Analytics this section will explain how you can safely prepare for and
upgrade your system to use our very latest releases.

Ensure that the database server has sufficient free space

This is especially important when performing major version upgrades (For example Matomo 4 -> Matomo 5).

If the database server does not have sufficient space, it could cause an error during the update and can result in the MySQL server becoming unresponsive (MySQL Server has gone away).

Schedule the upgrade and maintenance window

We recommend scheduling the migration and maintenance window ahead of time, as the Matomo system will be temporarily unavailable.

How long will an upgrade take?

• Patch releases (e.g. 3.0.4 to 3.0.5) and feature releases (eg. 3.0.5 to 3.1.0) typically require less than five minutes of downtime (and often no downtime).
• However major releases (e.g. 3.7.0 to 4.0.0) include data migrations and will take longer depending on storage performance and the amount of data.
• When installing a new plugin that includes data migration, it will also take longer. For example installing a new plugin that requires a database schema change on one of the log_* tables could take up to several hours.

There are also advanced and more complex techniques to upgrade your Matomo without any maintenance window or service interruption. Contact us for more information.

Download the latest Matomo Enterprise release

View instructions in Download the latest Matomo Enterprise release.

Start the maintenance window

Note: before you start the upgrade, we recommend you make a fresh Backup of your MySQL database and codebase.

Next we recommend enabling a maintenance window to effectively turn off all requests to the database.

Note: If you run Matomo on multiple servers (and config files and other files are on a shared folder), these commands only need to be executed on one of your servers.

Running the two following commands puts Matomo into maintenance:

• Turn off visitor tracking (Only do this step if you are not using the Queued Tracking Plugin to recover tracking data from the maintenance window)

  $ ./console config:set Tracker.record_statistics=0
  

• Turn off the Matomo user interface

  $ ./console config:set General.maintenance_mode=1
  

Disabling the tracking of new data helps the DB Schema updates to finish as soon as possible and without concurrent read/write errors. Disabling the Matomo User Interface will prevent users from accessing Matomo and making changes to the database while the upgrade is in process. A message will be displayed explaining that Matomo is undergoing maintenance.

When you put Matomo in maintenance, no data will be tracked during the maintenance window. There is a way to backfill the tracking requests and not lose any data during the migration: see the step below Recover maintenance window’s missing tracking data

Deploy Matomo to your servers

View instructions in Deploy Matomo to your servers and Deploy an upgrade.

Upgrade Matomo (note: this step may take a very long time)

Trigger the Matomo update by calling the core:update console command.

Run the following command on your Matomo server:

Note: If you run Matomo on multiple servers, this command core:update must be executed
only on one of your servers.

You will also need to ensure that the config.ini.php file is writable before running the core:update
command below.

$ ./path/to/matomo/console core:update --yes

The command will ask you for confirmation before starting the upgrade, unless you specify the --yes parameter which will cause the upgrade process to start automatically.

Once confirmed, that this step may take several hours or possibly even days, on very large Matomo databases when tracking million of requests each month.

Until which stage is it possible to rollback to a previous release?

As long as you haven’t confirmed and started the upgrade, you can safely rollback to the previously deployed codebase. As soon as you have started the upgrade you may not be able to rollback. Contact us for more information about Rollback strategies (when and how can a deployment can be safely rolled back).

If you run Matomo on multiple servers, clear the cache by calling the cache:clear command on each server.

Clearing caches after you deployed a new version ensures that all servers are synchronised and serving the most up to date Matomo assets.

$ ./path/to/matomo/console cache:clear

End the maintenance window

Note: If you run Matomo on multiple servers, these commands only need to be executed on one of your servers.

Now that Matomo is successfully upgraded, we can resume the tracking of user data and re-enable the user interface.

• Turn back on visitor tracking

  $ ./console config:set Tracker.record_statistics=1
  

• Turn back on the Matomo user interface

  $ ./console config:set General.maintenance_mode=0
  

(Optional) Recover maintenance window’s missing tracking data

Whenever Matomo is in maintenance mode, no data is being tracked into Matomo. However, there is a way to queue and replay the tracking requests after the maintenance window.

See: How to recover missing data during maintenance?

Go through Checklist: Post-deploy checks

You may go through each item in Checklist: Post-deploy checks to ensure the system is correctly deployed and working.